SMS senden

Dieser Leitfaden behandelt den Endpunkt für Einzelsendungen, POST /v1/sms/messages. Erstellen Sie eine JSON-Payload mit Empfänger, Absender, Text und Kategorie. Bird gibt 202 Accepted mit einer Nachrichten-ID zurück und stellt asynchron zu. Jede Anfrage sendet eine Nachricht an einen Empfänger. Um viele Nachrichten auf einmal zu senden, nutzen Sie den Batch-Versand. Um statt Ihres eigenen Textes eine Vorlage zu senden, geben Sie anstelle von text und category ein template-Objekt an. Integrierte Vorlagen lehnen from ab; Workspace-Vorlagen verlangen es.

Vor dem Senden: Zielland aktivieren

Ihr Workspace sendet SMS nur in die Länder auf seiner Zielland-Allowlist. Das Heimatland Ihrer Organisation ist das Land der Registrierungsadresse in ihrem Unternehmensprofil oder, wenn die Registrierungsadresse kein Land enthält, das Land der Rechnungsadresse. Ihr Workspace beginnt mit einer leeren Allowlist. Jedes Mal, wenn das Heimatland festgelegt oder geändert wird, fügt Bird dieses Land der Allowlist hinzu. Bird lehnt eine Sendung in ein Land, das nicht auf der Allowlist steht, mit 422 SMSDestinationNotEnabled ab, bevor ein Absender ermittelt wird. Aktivieren Sie die Länder, die Sie bedienen, im Dashboard unter SMS > Destinations.

Auf derselben Seite können Sie für jedes Land ein tägliches Ausgabenlimit in der Währung Ihres Wallets festlegen. Zum Festlegen benötigen Sie ein Organisations-Wallet und Lesezugriff darauf; zum Entfernen nicht. Ein Limit gilt unabhängig davon, ob das Land aktiviert ist. Sobald die heutigen Ausgaben für dieses Land das Limit erreichen, lehnt Bird neue Nachrichten dorthin bis Mitternacht UTC mit 422 SMSDestinationDailySpendExceeded ab. Auch Verifizierungsnachrichten werden abgelehnt. Ausgaben zählen, sobald eine Nachricht berechnet wird. Bereits angenommene Nachrichten können das Limit daher um ihre Kosten überschreiten. Eine Änderung an einem Limit braucht bis zu einer Minute, bis sie beim Versand wirkt.

Eine minimale Sendung

Die kleinste gültige Freitext-Payload besteht aus einem to-Empfänger, einem from-Absender, einem text-Text und einer category.

const msg = await bird.sms.send({
  from: "+15557654321",
  to: "+14155550100",
  text: "Your verification code is 123456.",
  category: "authentication",
});
console.log(msg.id, msg.status);

msg = client.sms.send(
    from_="+15557654321",
    to="+15551234567",
    text="Your verification code is 123456.",
    category="authentication",
)
print(msg.id, msg.status)

msg, err := client.Sms.Send(context.Background(), bird.SmsSendParams{
	From:     "+15557654321",
	To:       "+15551234567",
	Text:     "Your verification code is 123456.",
	Category: bird.SMSCategoryAuthentication,
})
if err != nil {
	log.Fatal(err)
}
fmt.Println(msg.Id, *msg.Status)

$message = $bird->sms->send(
    from: '+15557654321',
    to: '+15551234567',
    text: 'Your verification code is 123456.',
    category: 'authentication',
);
echo $message->getId(), ' ', $message->getStatus();

bird sms send --body-file - <<'JSON'
{
  "to": "+14155550100",
  "from": "+15557654321",
  "text": "Your verification code is 123456.",
  "category": "authentication",
  "options": {
    "smart_encoding": true
  },
  "tags": [
    {
      "name": "campaign",
      "value": "signup"
    }
  ],
  "metadata": {
    "user_id": "usr_12345"
  }
}
JSON

curl -X POST https://eu1.platform.bird.com/v1/sms/messages \
  -H "Authorization: Bearer bk_eu1_..." \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+31612345678",
    "from": "Bird",
    "text": "Your Bird verification code is 481920. It expires in 10 minutes.",
    "category": "authentication"
  }'

Verwenden Sie Ihren regionalen Host (https://us1.platform.bird.com oder https://eu1.platform.bird.com) mit einem passenden bk_{region}_...-Schlüssel. Die Antwort ist die angenommene Nachricht:

{
  "id": "sms_01ky7qmwgpfkybj9ecrnwjx714",
  "direction": "outbound",
  "status": "accepted",
  "to": "+31612345678",
  "from": "Bird",
  "text": "Your Bird verification code is 481920. It expires in 10 minutes.",
  "category": "authentication",
  "segments": { "count": 1, "encoding": "GSM_7BIT", "characters": 64 },
  "cost": null,
  "carrier": null,
  "mcc_mnc": null,
  "sent_at": null,
  "delivered_at": null,
  "created_at": "2026-07-23T14:56:34.326Z"
}

status: accepted bedeutet, dass Bird die Nachricht hat und sie verarbeitet; cost ist null, weil die Preisberechnung während der Verarbeitung erfolgt. Was danach geschieht, beschreibt das asynchrone Modell.

Die Payload aufbauen

Empfänger

to ist ein einzelner Empfänger im E.164-Format: ein führendes +, die Ländervorwahl und die Teilnehmernummer, etwa +31612345678. Eine Nachricht geht an genau einen Empfänger, ohne cc, bcc oder ein Empfänger-Array. Um viele Personen zu erreichen, senden Sie einen Batch.

Absender

from ist der Absender, den der Empfänger sieht. Bei einem Freitext-Versand ist er erforderlich, es sei denn, messaging_profile_id nennt ein Messaging-Profil mit einem Absender für das Zielland oder einem Standardabsender. Der Absender hat eine von zwei Formen, und welche davon funktionieren, hängt vom Zielland ab:

• Eine alphanumerische Absender-ID: 3 bis 11 Buchstaben, Ziffern, Leerzeichen, Bindestriche, Unterstriche oder Punkte, mit mindestens einem Buchstaben und ohne Trennzeichen am Anfang oder Ende, etwa Bird oder Acme-Co. Sie muss einen Buchstaben enthalten, daher wird eine Ziffernfolge mit Satzzeichen wie 555 555 abgelehnt. Manche Länder verlangen eine Registrierung, andere, darunter die USA, unterstützen keine alphanumerischen Absender. Empfänger können auf sie nicht antworten.
• Eine Nummer, die Ihr Workspace besitzt, im E.164-Format oder als reine Ziffern. Jeder rein numerische Wert in from wird als Nummer gelesen und unter Ihren Absendern gesucht, daher wird eine beliebige Nummer, die Ihnen nicht gehört, abgelehnt. Ob sie als Long Code, gebührenfreie Nummer oder Short Code dient, ergibt sich aus der Nummer selbst, nicht aus der Anzahl der Ziffern, die Sie eingeben. Ein 6-stelliger Wert in from ist nicht deshalb ein Short Code, weil er 6 Ziffern hat; er ist ein Short Code, wenn die Nummer, die Sie besitzen, einer ist.

Ein Absender, der für das Ziel nicht gültig ist, wird mit einem 422 abgelehnt, der den Grund nennt (zum Beispiel SMSAlphaNotSupported, wo alphanumerische Absender nicht verfügbar sind). Bei einem Versand mit integrierter Vorlage wird from nicht akzeptiert: Bird wählt einen Absender passend zu Ziel und Kategorie. Eine Workspace-Vorlage erfordert Ihren eigenen Absender in from oder ein Messaging-Profil, das einen liefert.

Wie Sie eine Absender-ID beantragen, welche Anforderungen jedes Land an sie stellt und wie Sie sie pro Land registrieren, beschreibt SMS-Absender-IDs.

Um die Absender und Standardwerte eines Programms an einer Stelle zu verwalten, erstellen Sie ein Messaging-Profil und nennen es in messaging_profile_id. Wenn Sie from weglassen, sendet Bird vom Absender des Profils für das Zielland oder von dessen Standardabsender. Fehlt category, gilt die Standardkategorie des Profils, und options.smart_encoding, cost_center, validity_period und options.callback_url übernehmen die Einstellungen des Profils. Werte, die Sie in der Nachricht setzen, haben Vorrang.

Nachrichtentext und Kategorie

text ist der Nachrichtentext mit mindestens einem Zeichen. Er wird in Segmenten abgerechnet und zugestellt; ein Versand ist auf 12 Segmente begrenzt (etwa 1.836 GSM-7-Zeichen oder 804, wenn der Text die erweiterte UCS-2-Kodierung nutzt). Ein Text über dieser Grenze wird mit einem 422 abgelehnt, nicht gekürzt.

category ist bei einem Freitext-Versand erforderlich, es sei denn, das Messaging-Profil in messaging_profile_id legt eine Standardkategorie fest. Das Feld ordnet die Nachricht als transactional, marketing, authentication oder service ein und teilt Bird und den Netzbetreibern so mit, warum Sie senden. Ein Einmal-Bestätigungscode nutzt authentication, eine Werbeaktion marketing. Wählen Sie die Kategorie, die zum Zweck der Nachricht passt.

Tags und Metadaten

Beide hängen Ihre eigenen Daten an einen Versand an, erfüllen aber unterschiedliche Aufgaben:

• tags sind strukturierte {name, value}-Paare (maximal 20 pro Versand; Name 1 bis 32 Zeichen, Wert 1 bis 64 Zeichen, nur ASCII [A-Za-z0-9_-], Groß- und Kleinschreibung wird unterschieden, Namen innerhalb eines Versands eindeutig). Sie sind vollwertige Filterdimensionen: Sie können die Nachrichtenliste nach Tag filtern. Verwenden Sie sie für Labels mit wenigen unterschiedlichen Werten wie campaign oder experiment_variant.
• metadata ist ein beliebiges JSON-Objekt (maximal 2 KB serialisiert). Es wird gespeichert, bei API-Abfragen zurückgegeben und bei jedem Webhook-Ereignis mitgesendet, ist aber keine Filterdimension. Verwenden Sie es für Kontext, den Sie zurückerhalten möchten: interne IDs, Fremdschlüssel und alles andere, was Ihnen mit jedem Ereignis zurückgegeben werden soll.
• reference ist eine Zeichenfolge mit 1 bis 255 Zeichen, über die Sie die Nachricht finden möchten, etwa eine Bestell- oder Ticketnummer. ?reference= in der Nachrichtenliste gleicht sie exakt und unter Beachtung der Groß- und Kleinschreibung ab, und mehrere Nachrichten können denselben Wert haben. Sie wird bei Abfragen zurückgegeben und bei jedem Webhook-Ereignis mitgesendet. Setzen Sie sie nur, wenn Sie danach suchen müssen, und legen Sie alle anderen Daten in metadata ab.

{
  "tags": [{ "name": "campaign", "value": "spring-2026" }],
  "metadata": { "user_id": "usr_12345", "order_id": "ord_98765" },
  "reference": "ord_98765"
}

Feldreferenz

* Freitext-Sendungen erfordern from, text und category, wobei ein Messaging-Profil from und category liefern kann. Vorlagen-Sendungen erfordern template statt text und category (und lehnen beide ab). Integrierte Vorlagen lehnen from ab; Workspace-Vorlagen erfordern es.

Mit einer Vorlage senden

Setzen Sie template, um eine integrierte Vorlage oder eine veröffentlichte Workspace-Vorlage zu senden. Das Erstellen von Workspace-Vorlagen ist als API-Vorschau verfügbar. Katalog, Variablen und Absenderregeln finden Sie unter SMS-Vorlagen.

Segmente und Kodierung

SMS wird pro Segment abgerechnet. Eine Nachricht, die in die GSM-7-Kodierung passt, erhält 160 Zeichen pro Einzelsegment; bei UCS-2 (ausgelöst durch Emojis, CJK- oder andere Nicht-GSM-Zeichen) sind es nur 70. Längere Nachrichten werden in mehrteilige Segmente mit etwas niedrigeren Grenzen pro Segment aufgeteilt. Jede Antwort meldet das aufgelöste segments: die abrechenbaren count, die encoding und die Zeichenanzahl. Segmente sind die Einheit, nach der abgerechnet wird; siehe Kosten.

Wenn ein Nachrichtentext nur wegen typografischer Zeichen außerhalb von GSM-7 liegt, kann Smart Encoding die Anzahl seiner Segmente verringern. Setzen Sie options.smart_encoding auf true, dann ersetzt Bird vor dem Senden typografische Anführungszeichen, Gedankenstriche, Auslassungspunkte und ähnliche Zeichen durch GSM-7-Entsprechungen. Die Funktion ist standardmäßig deaktiviert, weil sie den von Ihnen verfassten Text verändert.

Den vollständigen Zeichensatz, Zeichen aus der Erweiterungstabelle, die zwei Plätze belegen, die Größe von Emojis, die Ersetzungen durch Smart Encoding und die Berechnung der Segmente finden Sie unter Character limits.

Batch-Versand

POST /v1/sms/batches sendet bis zu 100 voneinander unabhängige Nachrichten in einer Anfrage. Das ist das Bulk-Muster für SMS: ein API-Aufruf für viele Empfänger. Batch-Anfragen unterliegen der Rate-Limit-Richtlinie sms_batch, getrennt von der Richtlinie sms_send für Einzelsendungen. Der Body ist ein JSON-Objekt, dessen Array messages die Nachrichtenobjekte aus Payload aufbauen enthält:

const result = await bird.sms.sendBatch({
  messages: [
    {
      from: "+15557654321",
      to: "+15551111111",
      text: "Hi Alice!",
      category: "marketing",
    },
    {
      from: "+15557654321",
      to: "+15552222222",
      text: "Hi Bob!",
      category: "marketing",
    },
  ],
});

batch = client.sms.send_batch(
    messages=[
        {
            "from_": "+15557654321",
            "to": "+15551111111",
            "text": "Hi Alice!",
            "category": "marketing",
        },
        {
            "from_": "+15557654321",
            "to": "+15552222222",
            "text": "Hi Bob!",
            "category": "marketing",
        },
    ]
)
for msg in batch.data:
    print(msg.id, msg.status)

batch, err := client.Sms.SendBatch(context.Background(), bird.SmsSendBatchParams{
	Messages: []bird.SmsSendParams{
		{
			From: "+15557654321", To: "+15551111111",
			Text: "Hi Alice!", Category: bird.SMSCategoryMarketing,
		},
		{
			From: "+15557654321", To: "+15552222222",
			Text: "Hi Bob!", Category: bird.SMSCategoryMarketing,
		},
	},
})
if err != nil {
	log.Fatal(err)
}
for _, msg := range batch.Data {
	fmt.Println(msg.Id, *msg.Status)
}

$batch = $bird->sms->sendBatch(messages: [
    (new SMSMessageSendRequest())
        ->setFrom('+15557654321')
        ->setTo('+15551111111')
        ->setText('Hi Alice!')
        ->setCategory('marketing'),
    (new SMSMessageSendRequest())
        ->setFrom('+15557654321')
        ->setTo('+15552222222')
        ->setText('Hi Bob!')
        ->setCategory('marketing'),
]);
foreach ($batch->getData() ?? [] as $item) {
    echo $item->getId(), ' ', $item->getStatus(), "\n";
}

curl -X POST "https://{region}.platform.bird.com/v1/sms/batches" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "to": "+15551111111",
        "from": "+15557654321",
        "text": "Hi Alice!",
        "category": "marketing"
      },
      {
        "to": "+15552222222",
        "from": "+15557654321",
        "text": "Hi Bob!",
        "category": "marketing"
      }
    ]
  }'

Die Validierung gilt nach dem Alles-oder-nichts-Prinzip: Ist eine Nachricht im Batch ungültig, wird die gesamte Anfrage mit 422 abgelehnt und nichts gesendet. Ein Batch wird also nie teilweise ausgeführt. Bei Erfolg enthält die Antwort 202 jede angenommene Nachricht in der Reihenfolge der Übermittlung unter data, dazu ein summary mit accepted_count. Ab dann ist jede Nachricht unabhängig: Scheitert die Zustellung an einen Empfänger, betrifft das die anderen nie.

Das asynchrone Modell: Was 202 bedeutet

Ein erfolgreicher Versand gibt 202 Accepted mit einer Nachrichten-ID und status: accepted zurück. Fehler in der Anfrage werden sofort gemeldet: Ein ungültiges Feld, ein Body über der Segmentobergrenze, ein Zielland, das Sie nicht aktiviert haben, oder ein ungültiger Absender führt zu 422. Ein Workspace ohne Guthaben in der Wallet erhält 402.

Die Zustellung erfolgt asynchron. Die Nachricht wechselt zu sent, sobald Bird sie an den Netzbetreiber übergibt. Eine Zustellbestätigung setzt anschließend delivered, undelivered, failed oder expired, sichtbar über Events und Webhooks und die Lese-Endpunkte. Daraus ergeben sich drei Folgen:

• Die Kosten werden nach der Annahme berechnet. Das Feld cost einer Nachricht ist bei der Annahme null und wird gefüllt, sobald Bird den Versand während der Verarbeitung bepreist. Lesen Sie die Nachricht erneut aus oder warten Sie auf das Zustell-Event, um die bisher berechneten Kosten zu sehen. Kosten und Abrechnung beschreibt die Bestandteile und wann einer davon unbepreist bleibt.
• Eine Nachricht kann nach dem 202 abgelehnt werden. Schlägt die Belastung während der Verarbeitung fehl, endet die Nachricht mit rejected und einem sms.rejected-Webhook, und Ihnen wird nichts berechnet. Eine leere Wallet erscheint als last_error.code: insufficient_balance.
• Lesezugriffe können kurz hinter dem 202 zurückliegen. Die Nachricht wird kurz nach 202 auf den Lese-Endpunkten sichtbar. Ein 404 direkt nach dem Versand löst sich daher innerhalb von Augenblicken von selbst.

Reservierte Felder

Bird lehnt die folgenden Anfragefelder mit 422 SMSUnsupportedFeature ab:

scheduled_at, media_urls, broadcast_id, campaign_id, audience_id, contact_id, topic_id, personalization, options.max_price_per_segment, options.track_clicks (wenn true)

Nehmen Sie diese Felder nicht in einen Versand auf.

Sicher erneut versuchen

Senden Sie den Header Idempotency-Key mit einem eindeutigen Wert pro logischem Versand. Wenn eine Anfrage erfolgreich ist, aber keine Antwort zurückkommt, wiederholen Sie dieselbe Anfrage mit demselben Schlüssel. Bird gibt dann das ursprüngliche Ergebnis zurück, statt eine doppelte Nachricht zu senden. Schlüsselformat und Aufbewahrungsdauer finden Sie unter Idempotenz.

Kosten und Abrechnung

Ausgehende SMS werden pro Segment abgerechnet. Der Preis hängt vom Zielland und vom Netzbetreiber ab. Manche Routen enthalten einen Zuschlag eines Drittanbieters, etwa die Netzbetreibergebühren für US 10DLC.

Das Feld cost einer Nachricht teilt die Gebühr in benannte Bestandteile auf. transaction_amount ist der Betrag, den Bird für die Zustellung der Nachricht berechnet hat. passthrough_amount ist eine weitergegebene Gebühr eines Drittanbieters. amount ist die Summe der bereits bepreisten Bestandteile in currency_code. Ein noch nicht bepreister Bestandteil ist null statt "0.00000". Bei einer Nachricht, deren Zuschlag nie ermittelt wurde, enthält amount daher nur die Zustellgebühr. Die Nachrichtenreferenz dokumentiert jedes Feld.

Der Zuschlag wird nach bestem Bemühen ermittelt. Bird ermittelt ihn beim Erfassen der Zustellbestätigung innerhalb eines begrenzten Zeitfensters. Gelingt das in diesem Zeitfenster nicht, bleibt passthrough_amount dauerhaft null: Bird versucht es nicht erneut, und amount bleibt die Zustellgebühr.

Eingehende SMS werden in zwei Posten abgerechnet: mit dem eingehenden Tarif pro Segment und, falls zutreffend, mit einem eingehenden Netzbetreiberzuschlag. Beide erscheinen im Feld cost der empfangenen Nachricht selbst: der Tarif als transaction_amount, der Zuschlag als passthrough_amount. Anders als beim ausgehenden Gegenstück wird der eingehende Zuschlag bei der Annahme der Nachricht bepreist, nicht bei der Zustellung. Er wird daher nie nachträglich ausgefüllt.

Kosten und Segmente pro Nachricht prüfen Sie im SMS-Log.

Nächste Schritte

• SMS-Vorlagen: Senden Sie eine integrierte Vorlage und lassen Sie Bird den Absender auswählen.
• SMS-Log: Suchen Sie eine Nachricht und prüfen Sie ihren Lebenszyklus, ihre Segmente und ihre Kosten.
• Events: Empfangen Sie Zustellungsereignisse in Ihren Systemen.
• SMS-Callback-URLs: Senden Sie die Ereignisse einer einzelnen Nachricht oder eines einzelnen Profils an einen eigenen HTTPS-Endpunkt.
• SMS-Metriken: Überwachen Sie Zustellrate, Fehlerrate und angenommenes Volumen.
• Idempotenz: Versuchen Sie Anfragen mit dem Header Idempotency-Key sicher erneut.
• Ihre erste SMS senden: ein Video, das dieselbe Einrichtung im Dashboard Schritt für Schritt zeigt