Wysyłanie

Wyślij SMS za pomocą POST /v1/messages

Wyświetl jako Markdown Specyfikacja OpenAPI

POST/v1/messages

Wyślij jeden tekst na jeden numer. Koszt jest pobierany z salda, gdy żądanie zostanie zaakceptowane.

Treść żądania

tostringwymagane
Numer w formacie międzynarodowym, na przykład +14155550123. Spacje, myślniki, nawiasy i prefiks 00 są usuwane.
textstringwymagane
Wiadomość. Do 10 segmentów; zobacz Tekst i segmenty.
referencestringopcjonalne
Twój własny identyfikator, do 100 znaków. Powraca w obiekcie wiadomości i w każdym webhooku.
send_atstringopcjonalne
Czas wysłania w formacie ISO 8601, od 2 minut do 45 dni w przyszłość. Bez tego wiadomość jest natychmiast umieszczana w kolejce.

Dodaj nagłówek Idempotency-Key, aby bezpiecznie ponawiać próby: zobacz Idempotency.

curl https://bulksmsapi.cc/v1/messages \
  -H "Authorization: Bearer $BULKSMSAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+14155550123",
    "text": "Your Northwind code is 482913. It expires in 10 minutes.",
    "reference": "login-7781"
  }'

// Node.js 18 or newer (built-in fetch)
const res = await fetch("https://bulksmsapi.cc/v1/messages", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.BULKSMSAPI_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    to: "+14155550123",
    text: "Your Northwind code is 482913. It expires in 10 minutes.",
    reference: "login-7781",
  }),
});
const message = await res.json();
console.log(res.status, message.id, message.status, message.price);

# Python 3, standard library only
import json, os, urllib.request

req = urllib.request.Request(
    "https://bulksmsapi.cc/v1/messages",
    data=json.dumps({
        "to": "+14155550123",
        "text": "Your Northwind code is 482913. It expires in 10 minutes.",
        "reference": "login-7781",
    }).encode(),
    headers={
        "Authorization": "Bearer " + os.environ["BULKSMSAPI_KEY"],
        "Content-Type": "application/json",
        "User-Agent": "northwind-app/1.0",
    },
    method="POST",
)
with urllib.request.urlopen(req) as res:
    message = json.load(res)
print(res.status, message["id"], message["status"], message["price"])

<?php
// PHP 7.4 or newer with the curl extension
$ch = curl_init("https://bulksmsapi.cc/v1/messages");
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer " . getenv("BULKSMSAPI_KEY"),
        "Content-Type: application/json",
    ],
    CURLOPT_POSTFIELDS => json_encode([
        "to" => "+14155550123",
        "text" => "Your Northwind code is 482913. It expires in 10 minutes.",
        "reference" => "login-7781",
    ]),
]);
$message = json_decode(curl_exec($ch), true);
echo curl_getinfo($ch, CURLINFO_HTTP_CODE), " ", $message["id"], " ", $message["status"], "\n";

// Go 1.20 or newer, standard library only
package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"net/http"
	"os"
)

func main() {
	body, _ := json.Marshal(map[string]any{
		"to":        "+14155550123",
		"text":      "Your Northwind code is 482913. It expires in 10 minutes.",
		"reference": "login-7781",
	})
	req, _ := http.NewRequest("POST", "https://bulksmsapi.cc/v1/messages", bytes.NewReader(body))
	req.Header.Set("Authorization", "Bearer "+os.Getenv("BULKSMSAPI_KEY"))
	req.Header.Set("Content-Type", "application/json")
	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()
	var message map[string]any
	json.NewDecoder(res.Body).Decode(&message)
	fmt.Println(res.StatusCode, message["id"], message["status"], message["price"])
}

202 AcceptedJSON

{
  "id": "msg_8F3K2Q9TZ1MX",
  "object": "message",
  "batch_id": "bat_4M7Q1X0PK2RS",
  "to": "+14155550123",
  "country": "US",
  "text": "Your Northwind code is 482913. It expires in 10 minutes.",
  "segments": 1,
  "price": "0.00507",
  "currency": "USD",
  "status": "queued",
  "error": null,
  "reference": "login-7781",
  "created_at": "2026-11-07T09:30:12.418Z",
  "sent_at": null,
  "done_at": null
}

Obiekt wiadomości

Pola

idstring
Identyfikator wiadomości, msg_ następnie 12 znaków.
objectstring
Zawsze wiadomość.
batch_idstring
Partia, do której należy wiadomość (pojedyncza wiadomość również otrzymuje partię).
tostring
Numer w formacie E.164 po oczyszczeniu.
countrystring
Kod ISO 3166 kraju, dla którego numer został wyceniony.
textstring
Tekst wysłany, pola scalające wypełnione.
segmentsinteger
Liczba segmentów SMS, których używa tekst.
pricestring
Cena tej wiadomości w USD, 5 miejsc po przecinku (cena za segment razy segmenty).
currencystring
Zawsze USD.
statusstring
zaplanowane, w kolejce, wysłane, dostarczone, nieudane lub anulowane.
errorobject or null
Dla wiadomości nieudanych lub anulowanych: kod i wiadomość.
referencestring or null
Twój własny odnośnik z żądania.
created_atstring
Kiedy żądanie zostało zaakceptowane (ISO 8601, UTC).
sent_atstring or null
Kiedy wiadomość została przekazana do sieci.
done_atstring or null
Kiedy ustawiono końcowy status (dostarczone, nieudane lub anulowane).

Pobierz wiadomość

GET/v1/messages/{id}

Jedna wiadomość według jej msg_ id. Wiadomości innych kont zwracają 404.

curl https://bulksmsapi.cc/v1/messages/msg_8F3K2Q9TZ1MX \
  -H "Authorization: Bearer $BULKSMSAPI_KEY"

const res = await fetch("https://bulksmsapi.cc/v1/messages/msg_8F3K2Q9TZ1MX", {
  headers: { Authorization: `Bearer ${process.env.BULKSMSAPI_KEY}` },
});
const message = await res.json();
console.log(message.status, message.error);

import json, os, urllib.request

req = urllib.request.Request(
    "https://bulksmsapi.cc/v1/messages/msg_8F3K2Q9TZ1MX",
    headers={"Authorization": "Bearer " + os.environ["BULKSMSAPI_KEY"], "User-Agent": "northwind-app/1.0"},
)
with urllib.request.urlopen(req) as res:
    message = json.load(res)
print(message["status"], message["error"])

<?php
$ch = curl_init("https://bulksmsapi.cc/v1/messages/msg_8F3K2Q9TZ1MX");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ["Authorization: Bearer " . getenv("BULKSMSAPI_KEY")],
]);
$message = json_decode(curl_exec($ch), true);
echo $message["status"], "\n";

package main

import (
	"encoding/json"
	"fmt"
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("GET", "https://bulksmsapi.cc/v1/messages/msg_8F3K2Q9TZ1MX", nil)
	req.Header.Set("Authorization", "Bearer "+os.Getenv("BULKSMSAPI_KEY"))
	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()
	var message map[string]any
	json.NewDecoder(res.Body).Decode(&message)
	fmt.Println(message["status"], message["error"])
}

Listuj wiadomości

GET/v1/messages

Wiadomości konta, od najnowszych.

Parametry zapytania

batch_idstringopcjonalne
Tylko wiadomości z tej partii bat_.
statusstringopcjonalne
zaplanowane, w kolejce, wysłane, dostarczone, nieudane lub anulowane.
limitintegeropcjonalne
1 do 100, domyślnie 20.
starting_afterstringopcjonalne
Id msg_: strona zaczyna się po nim. Użyj ostatniego id z poprzedniej strony.

curl "https://bulksmsapi.cc/v1/messages?status=failed&limit=50" \
  -H "Authorization: Bearer $BULKSMSAPI_KEY"

200 OKJSON

{
  "object": "list",
  "data": [ { "id": "msg_8F3K2Q9TZ1MX", "object": "message", "status": "failed", "...": "..." } ],
  "has_more": false
}

PoprzednieUwierzytelnianie DalejPartie