Menghantar

Hantar SMS dengan POST /v1/messages

Lihat sebagai Markdown Spesifikasi OpenAPI

POST/v1/messages

Hantar satu teks ke satu nombor. Kos diambil dari saldo apabila permintaan diterima.

Badan permintaan

tostringdiperlukan
Nombor dalam format antarabangsa, contohnya +14155550123. Ruang, sengkang, kurungan dan awalan 00 akan dibersihkan.
textstringdiperlukan
Mesej. Sehingga 10 segmen; lihat Teks dan segmen.
referencestringpilihan
ID anda sendiri, sehingga 100 aksara. Ia akan kembali dalam objek mesej dan dalam setiap webhook.
send_atstringpilihan
Masa ISO 8601 untuk menghantar, 2 minit hingga 45 hari ke hadapan. Tanpanya, mesej akan disusun segera.

Tambah header Idempotency-Key untuk menjadikan percubaan semula selamat: lihat Idempotensi.

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
}

Objek mesej

Medan

idstring
ID mesej, msg_ diikuti oleh 12 aksara.
objectstring
Sentiasa mesej.
batch_idstring
Batch yang dimiliki oleh mesej (satu mesej tunggal juga mendapat batch).
tostring
Nombor dalam format E.164, selepas dibersihkan.
countrystring
Kod ISO 3166 negara yang nombor itu diberi harga.
textstring
Teks seperti yang dihantar, medan gabungan diisi.
segmentsinteger
Bilangan segmen SMS yang digunakan oleh teks.
pricestring
Harga mesej ini dalam USD, 5 perpuluhan (harga per segmen kali segmen).
currencystring
Sentiasa USD.
statusstring
dijadualkan, dalam barisan, dihantar, dihantar, gagal atau dibatalkan.
errorobject or null
Untuk mesej yang gagal atau dibatalkan: kod dan mesej.
referencestring or null
Rujukan anda sendiri dari permintaan.
created_atstring
Apabila permintaan diterima (ISO 8601, UTC).
sent_atstring or null
Apabila mesej diserahkan kepada rangkaian.
done_atstring or null
Apabila status akhir (dihantar, gagal atau dibatalkan) ditetapkan.

Dapatkan satu mesej

GET/v1/messages/{id}

Satu mesej mengikut ID msg_nya. Mesej dari akaun lain akan menjawab 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"])
}

Senaraikan mesej

GET/v1/messages

Mesej akaun, yang terbaru dahulu.

Parameter carian

batch_idstringpilihan
Hanya mesej bagi kumpulan bat_ ini.
statusstringpilihan
dijadualkan, dalam barisan, dihantar, dihantar, gagal atau dibatalkan.
limitintegerpilihan
1 hingga 100, lalai 20.
starting_afterstringpilihan
ID msg_: halaman bermula selepasnya. Gunakan ID terakhir dari halaman sebelumnya.

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
}

SebelumnyaPengesahan SeterusnyaBatches