Loslegen

Schnellstart: Senden Sie Ihre erste SMS über die API

Als Markdown anzeigen OpenAPI-Spezifikation

Diese Anleitung führt Sie vom Kontoerstellen bis zur zugestellten Nachricht und einem signierten Zustellungsereignis. Sie benötigen ein Terminal und fünf Minuten.

1. Konto erstellen und Guthaben aufladen

Öffnen Sie API-Schlüssel erhalten. Ihr Browser erstellt einen Kontoschlüssel, der mit acct_ beginnt; kopieren Sie ihn oder speichern Sie ihn als Datei, dann bestätigen Sie. Dieser Schlüssel ist Ihr Login für die Konsole. Fügen Sie Guthaben auf der Rechnungsseite hinzu: Der gehostete Checkout öffnet sich in der Konsole, und das Guthaben wird oben auf jeder Konsolenseite angezeigt.

2. API-Schlüssel erstellen

Benennen Sie auf der API-Schlüssel-Seite einen Schlüssel (z.B. production oder staging) und erstellen Sie ihn. Der Schlüssel beginnt mit bsa_live_ und wird einmal angezeigt: kopieren Sie ihn in Ihren Secret Store oder eine Umgebungsvariable.

export BULKSMSAPI_KEY="bsa_live_..."

3. Nachricht senden

Senden Sie einen Text an Ihr eigenes Telefon. Nummern werden im internationalen Format mit dem Pluszeichen geschrieben.

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"])
}

Die Antwort ist 202 Accepted mit einer Nachrichten-ID, dem Preis und dem Status queued. Innerhalb von Sekunden wechselt der Status zu sent und dann zu delivered.

4. Status abrufen

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"])
}

5. Batch senden

Ein Batch sendet einen Text an bis zu 10.000 Nummern. Duplikate und Nummern, die nicht gelesen werden können, werden in set_aside aufgeführt und nicht berechnet.

curl https://bulksmsapi.cc/v1/batches \
  -H "Authorization: Bearer $BULKSMSAPI_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: spring-sale-0412" \
  -d '{
    "name": "Spring sale",
    "text": "Spring sale at Northwind: 20% off until Sunday. Opt out: northwind.example/sms",
    "to": [
      "+14155550123",
      "+447400123456",
      "+4915123456789"
    ]
  }'

const res = await fetch("https://bulksmsapi.cc/v1/batches", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.BULKSMSAPI_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": "spring-sale-0412",
  },
  body: JSON.stringify({
    name: "Spring sale",
    text: "Spring sale at Northwind: 20% off until Sunday. Opt out: northwind.example/sms",
    to: ["+14155550123", "+447400123456", "+4915123456789"],
  }),
});
const batch = await res.json();
console.log(res.status, batch.id, batch.recipients, batch.cost);

import json, os, urllib.request

req = urllib.request.Request(
    "https://bulksmsapi.cc/v1/batches",
    data=json.dumps({
        "name": "Spring sale",
        "text": "Spring sale at Northwind: 20% off until Sunday. Opt out: northwind.example/sms",
        "to": ["+14155550123", "+447400123456", "+4915123456789"],
    }).encode(),
    headers={
        "Authorization": "Bearer " + os.environ["BULKSMSAPI_KEY"],
        "Content-Type": "application/json",
        "Idempotency-Key": "spring-sale-0412",
        "User-Agent": "northwind-app/1.0",
    },
    method="POST",
)
with urllib.request.urlopen(req) as res:
    batch = json.load(res)
print(res.status, batch["id"], batch["recipients"], batch["cost"])

<?php
$ch = curl_init("https://bulksmsapi.cc/v1/batches");
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer " . getenv("BULKSMSAPI_KEY"),
        "Content-Type: application/json",
        "Idempotency-Key: spring-sale-0412",
    ],
    CURLOPT_POSTFIELDS => json_encode([
        "name" => "Spring sale",
        "text" => "Spring sale at Northwind: 20% off until Sunday. Opt out: northwind.example/sms",
        "to" => ["+14155550123", "+447400123456", "+4915123456789"],
    ]),
]);
$batch = json_decode(curl_exec($ch), true);
echo $batch["id"], " ", $batch["recipients"], " ", $batch["cost"], "\n";

package main

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

func main() {
	body, _ := json.Marshal(map[string]any{
		"name": "Spring sale",
		"text": "Spring sale at Northwind: 20% off until Sunday. Opt out: northwind.example/sms",
		"to":   []string{"+14155550123", "+447400123456", "+4915123456789"},
	})
	req, _ := http.NewRequest("POST", "https://bulksmsapi.cc/v1/batches", bytes.NewReader(body))
	req.Header.Set("Authorization", "Bearer "+os.Getenv("BULKSMSAPI_KEY"))
	req.Header.Set("Content-Type", "application/json")
	req.Header.Set("Idempotency-Key", "spring-sale-0412")
	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()
	var batch map[string]any
	json.NewDecoder(res.Body).Decode(&batch)
	fmt.Println(res.StatusCode, batch["id"], batch["recipients"], batch["cost"])
}

6. Zustellungsereignisse empfangen

Fügen Sie auf der Webhooks-Seite einen HTTPS-Endpunkt hinzu. Jede zugestellte oder fehlgeschlagene Nachricht ruft ihn mit einem signierten JSON-Ereignis auf; überprüfen Sie die Signatur mit dem Code auf der Webhooks-Seite und antworten Sie mit einem beliebigen 2xx-Status.

Weiter: Lesen Sie Batches für personalisierten Text pro Nummer und Zeitplanung sowie Errors für jeden Fehlercode und dessen Bedeutung für Ihr Guthaben.

ZurückAPI-Überblick WeiterAuthentifizierung