Sign inGet Started

Ihre erste E-Mail senden

Erstellen Sie einen API-Schlüssel, senden Sie über die gemeinsame Onboarding-Domain von Bird und prüfen Sie das Ergebnis. Für diese Anleitung müssen Sie weder eine Absenderdomain verifizieren noch DNS-Einträge veröffentlichen. Verifizieren Sie Ihre eigene Domain, bevor Sie an Kunden senden.

1. Einen API-Schlüssel erstellen

Öffnen Sie im Dashboard Platform tools > API keys und erstellen Sie einen Schlüssel. Schlüssel gelten jeweils für eine Region und sehen aus wie bk_us1_... oder bk_eu1_.... Die Region im Präfix gibt an, welchen API-Host Sie aufrufen: https://us1.platform.bird.com oder https://eu1.platform.bird.com.

Die Seite API Keys im Bird-Dashboard mit einer Liste der Schlüssel samt maskiertem Präfix, Berechtigungen und Zeitpunkt der letzten Nutzung

Der vollständige Schlüssel wird nur einmal angezeigt, beim Erstellen. Kopieren Sie ihn an einen sicheren Ort und exportieren Sie ihn dann, damit die Code-Beispiele in Schritt 2 ihn lesen können:

Codebeispiel
export BIRD_API_KEY="bk_us1_..."

2. Eine E-Mail senden

Senden Sie von onboarding@messagebird.dev, der gemeinsamen Onboarding-Domain von Bird, die ohne Einrichtung in Ihrem Workspace verfügbar ist. Adressieren Sie die E-Mail an delivered@messagebird.dev, einen Sandbox-Empfänger, an den immer zugestellt wird. So ist das Ergebnis ohne echtes Postfach vorhersagbar.

Der cURL-Aufruf verwendet den US-Host. Wenn Ihr Schlüssel mit bk_eu1_ beginnt, rufen Sie stattdessen https://eu1.platform.bird.com auf. Das SDK liest die Region aus Ihrem Schlüssel und wählt den Host aus. Der TypeScript-Tab erfordert npm install @messagebird/sdk.

import { BirdClient } from "@messagebird/sdk";

const bird = new BirdClient({ apiKey: process.env.BIRD_API_KEY! });

const msg = await bird.email.send({
  from: { email: "onboarding@messagebird.dev", name: "Bird" },
  to: ["delivered@messagebird.dev"],
  subject: "Hello from Bird",
  html: "<p>My first Bird email.</p>",
});

console.log(msg.id, msg.status);

Vollständige Schritte zur Installation und Ausführung in jeder Sprache und jedem Framework finden Sie in den SDK-Quickstarts.

3. Ergebnis prüfen

Die API antwortet mit 202: Bird hat den Versand zur asynchronen Verarbeitung angenommen. Prüfen Sie den Zustellstatus separat. Die Felder unter *_count verfolgen die Empfänger durch die Zustellstatus. In der ersten Antwort ist ein Empfänger angenommen und keiner zugestellt.

Codebeispiel
{
  "id": "em_01ky7ma8y2es1s2akzk53tmjn0",
  "status": "accepted",
  "category": "marketing",
  "from": { "email": "onboarding@messagebird.dev" },
  "to": [{ "email": "delivered@messagebird.dev" }],
  "subject": "Hello from Bird",
  "accepted_count": 1,
  "processed_count": 0,
  "delivered_count": 0,
  "deferred_count": 0,
  "bounced_count": 0,
  "complained_count": 0,
  "rejected_count": 0,
  "open_count": 0,
  "click_count": 0,
  "track_opens": true,
  "track_clicks": true,
  "created_at": "2026-07-23T13:58:20.866Z"
}

Rufen Sie die Nachricht über ihre em_-ID ab, um ihren aktuellen Status zu sehen. Eine Nachricht durchläuft die Status accepted, processed und delivered. Fragen Sie den Status ab, bis die Sandbox-Nachricht delivered erreicht:

const msg = await bird.email.get("em_abc123");
msg.status; // "accepted" | "processed" | "delivered" | "bounced" | …
msg.delivered_count;
msg.bounced_count;
console.log(msg.subject, msg.subject_recipient_id);

Ersetzen Sie im cURL-Tab {region} und {message_id}, und verwenden Sie $BIRD_API_KEY anstelle von $TOKEN.

Die Abfrage zeigt jetzt status: "delivered", delivered_count: 1 und einen Zeitstempel delivered_at. Was delivered bei einem echten Empfänger belegt, beschreibt der Leitfaden zu Events.

Da Sie an delivered@messagebird.dev gesendet haben, steht das Ergebnis fest: Die Nachricht durchläuft die echte Zustellpipeline von Bird, einschließlich der Event- und Webhook-Formate aus der Produktion, erreicht aber nie ein echtes Postfach. Um einen Bounce zu testen, senden Sie an bounce@messagebird.dev. Der Leitfaden zur Test-Sandbox listet alle Sandbox-Adressen und ihr simuliertes Ergebnis auf.

Die Onboarding-Domain

Der gemeinsame Absender onboarding@messagebird.dev steht für das Onboarding bereit und hat folgende Grenzen:

  • Außer an die Sandbox-Adressen von @messagebird.dev stellt er nur an verifizierte Mitglieder Ihres Workspace zu; jeder andere Empfänger wird mit 422 abgelehnt.
  • Der Versand ist auf 50 Empfänger pro Organisation und UTC-Tag begrenzt. Dabei zählt jede Adresse in to, cc und bcc, auch Sandbox-Empfänger. Oberhalb der Grenze gibt die API einen 429 zurück.

Wenn Sie echten Kunden E-Mails senden möchten, verifizieren Sie Ihre eigene Absenderdomain und tragen Sie Ihre eigene Adresse in from ein; alles andere in der Anfrage bleibt gleich.

Nächste Schritte

  • Quickstarts pro SDK: derselbe Ablauf in Ihrer Sprache und Ihrem Framework.
  • Absenderdomains: Verifizieren Sie Ihre eigene Domain für den Versand im Produktivbetrieb.
  • Test-Sandbox: alle Sandbox-Adressen und die Ereignisse, die sie auslösen.
  • Referenz der E-Mail-API: das vollständige Anfrage- und Antwortschema.
  • Erste Schritte mit E-Mail: ein Video zum Onboarding im Dashboard, das über diese Seite hinausgeht und eine Absenderdomain mit ihren DNS-Einträgen hinzufügt