E-Mail senden

Ein minimaler Versand

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); // "em_…", "accepted"

msg = client.email.send(
    from_={"email": "onboarding@messagebird.dev", "name": "Bird"},
    to=["delivered@messagebird.dev"],
    subject="Hello from Bird",
    html="<p>My first Bird email.</p>",
)
print(msg.id, msg.status)

package main

import (
	"context"
	"fmt"
	"log"
	"os"

	bird "github.com/messagebird/bird-sdk-go"
	"github.com/messagebird/bird-sdk-go/option"
)

func main() {
	client, err := bird.NewClient(option.WithAPIKey(os.Getenv("BIRD_API_KEY")))
	if err != nil {
		log.Fatal(err)
	}
	msg, err := client.Email.Send(context.Background(), bird.EmailSendParams{
		From:    "onboarding@messagebird.dev",
		To:      []string{"delivered@messagebird.dev"},
		Subject: "Hello from Bird",
		HTML:    "<p>My first Bird email.</p>",
	})
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(msg.Id, *msg.Status)
}

$message = $bird->email->send(
    from: 'Bird <onboarding@messagebird.dev>',
    to: ['delivered@messagebird.dev'],
    subject: 'Hello from Bird',
    html: '<p>My first Bird email.</p>',
);
echo $message->getId(), ' ', $message->getStatus();

bird email send \
  --from hello@yourdomain.com \
  --html '<p>It works.</p>' \
  --subject 'Hello from Bird' \
  --to delivered@messagebird.dev

curl -X POST https://us1.platform.bird.com/v1/email/messages \
  -H "Authorization: Bearer bk_us1_..." \
  -H "Content-Type: application/json" \
  -d '{
    "from": "hello@yourdomain.com",
    "to": ["delivered@messagebird.dev"],
    "subject": "Hello from Bird",
    "html": "<p>It works.</p>"
  }'

Versand vor der Domain-Verifizierung

Payload aufbauen

Empfänger

Inhalt

Reply-to und benutzerdefinierte Header

• Adressierungs- und Plattform-Header. Legen Sie die Adressierung der Nachricht über die dafür vorgesehenen Felder fest (from, to, cc, bcc, reply_to, subject). Diese Namen und die Header, die wir für Sie generieren (Content-Type, Content-Transfer-Encoding, DKIM-Signature, Received, Return-Path), können hier nicht gesetzt werden.
• List-Unsubscribe und List-Unsubscribe-Post bei einem marketing-Send. Wir setzen einen konformen One-Click-Unsubscribe-Header bei diesen selbst. Bei einem transactional-Send belassen wir Ihre genau so, wie Sie sie gesetzt haben.
• Jeder Wert mit einem Wagenrücklauf oder Zeilenumbruch.

Tracking

Kategorie und IP-Pool

Feldreferenz

Versand mit einem Template

const msg = await bird.email.send({
  from: { email: "onboarding@messagebird.dev", name: "Bird" },
  to: ["delivered@messagebird.dev"],
  category: "transactional",
  template: {
    slug: "welcome-email",
    parameters: { first_name: "Jane" },
  },
});
console.log(msg.id, msg.status);

msg = client.email.send(
    from_={"email": "onboarding@messagebird.dev", "name": "Bird"},
    to=["delivered@messagebird.dev"],
    category="transactional",
    template="welcome-email",
    parameters={"first_name": "Jane"},
)
print(msg.id, msg.status)

msg, err := client.Email.Send(context.Background(), bird.EmailSendParams{
	From:       "onboarding@messagebird.dev",
	To:         []string{"delivered@messagebird.dev"},
	Category:   "transactional",
	Template:   "welcome-email",
	Parameters: map[string]any{"first_name": "Jane"},
})
if err != nil {
	log.Fatal(err)
}
fmt.Println(msg.Id, *msg.Status)

$message = $bird->email->send(
    from: 'Bird <onboarding@messagebird.dev>',
    to: ['delivered@messagebird.dev'],
    category: 'transactional',
    template: (new EmailMessageSendRequestTemplate())
        ->setSlug('welcome-email')
        ->setParameters(['first_name' => 'Jane']),
);
echo $message->getId(), ' ', $message->getStatus();

bird email send \
  --category transactional \
  --from hello@yourdomain.com \
  --parameters '{"first_name":"Jane"}' \
  --template welcome-email \
  --to delivered@messagebird.dev

curl -X POST https://us1.platform.bird.com/v1/email/messages \
  -H "Authorization: Bearer bk_us1_..." \
  -H "Content-Type: application/json" \
  -d '{
    "from": "hello@yourdomain.com",
    "to": ["delivered@messagebird.dev"],
    "category": "transactional",
    "template": {
      "slug": "welcome-email",
      "parameters": { "first_name": "Jane" }
    }
  }'

• Inline oder Template, niemals beides. Das gleichzeitige Senden von template zusammen mit subject, html oder text wird mit einem 422 abgelehnt. Der API lehnt auch Variablenwerte im Top-Level-Feld parameters ab; bei einem Template-Send gehören sie in template.parameters.
• bird ist der einzige reservierte Name. Ein Platzhalter-Pfad, der mit bird. beginnt, benennt unsere eigenen Daten, wie den Abmeldelink oder den Kontaktdatensatz des Empfängers. Daher darf ein template.parameters-Schlüssel nicht bird heißen. Alle anderen Schlüssel können Sie frei definieren, und jeder ist ein einzelnes flaches Wort: {"order_number": "A-1043"} füllt {{ order_number }}.
• Ein Template kann sofort oder später senden. Fügen Sie scheduled_at hinzu, um den Versand zu planen. Wir pinnen die veröffentlichte Version, die gewählte Sprache und die Parameterwerte bei der Annahme. Löschen Sie das Template vor dem Versandzeitpunkt, wird die Nachricht mit generation_failure abgelehnt.
• Ein Versand verwendet die veröffentlichte Version des Templates. Entwürfe werden nie gesendet. Ein unbekanntes Template wird mit einem 404 abgelehnt, und ein Template ohne veröffentlichte Version mit einem 422.
• language wählt eine der Sprachen des Templates. Lassen Sie es weg, um die Standardsprache des Templates zu senden. Fordern Sie eine Sprache an, die das Template nicht hat, und die eigene on_missing_language-Einstellung entscheidet, ob stattdessen die nächste Übereinstimmung gesendet wird oder der Versand abgelehnt wird. Ein Template, das language_source_required setzt, lehnt einen Versand ab, der gar keine Sprache benennt.
• Die Kategorie des Templates ist ein Standardwert, und Ihre überschreibt ihn. Lassen Sie category weg, und der Versand erbt die Kategorie des Templates. Ein transaktionales Template muss sie also nicht bei jedem Aufruf wiederholen.

Tags vs. Metadaten

• tags sind strukturierte {name, value}-Paare: bis zu 20 pro Send, Name bis zu 32 Zeichen, Wert bis zu 64, nur ASCII-Buchstaben, Ziffern, Unterstrich und Bindestrich, und Namen innerhalb des Sends eindeutig. Tags sind Filterdimensionen, sodass Sie die Nachrichtenliste nach Tag filtern und Analytics sowie Dashboard-Rollups nach Tag aufschlüsseln können. Verwenden Sie sie für Labels mit geringer Kardinalität wie campaign, experiment_variant oder source.
• metadata ist ein beliebiges JSON-Objekt, bis zu 2 KB serialisiert. Wir speichern es, geben es bei API-Lesevorgängen zurück und liefern es bei jedem Webhook-Event mit. Damit eignet es sich für Kontext, den Sie zurückerhalten möchten: interne IDs, Fremdschlüssel, strukturierte Payloads.

{
  "tags": [{ "name": "campaign", "value": "onboarding" }],
  "metadata": { "user_id": "usr_12345", "order_id": "ord_98765" }
}

Anhänge

Was eine 202 bedeutet

{
  "id": "em_01ky7ma8y2es1s2akzk53tmjn0",
  "status": "accepted",
  "category": "marketing",
  "from": { "email": "hello@yourdomain.com" },
  "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"
}

• Lesevorgänge liefern den Status ohne den Body. GET /v1/email/messages/{message_id} gibt den Nachrichten- und Empfängerstatus zurück, nie den html- oder text-Body. Wenn die Inhaltsspeicherung für den Workspace aktiviert ist, bleiben gespeicherte Bodys bis zu 30 Tage über GET /v1/email/messages/{message_id}/content verfügbar.
• Ein Lesevorgang kann dem Versand kurz hinterherhinken. Ein 404 auf den Lese-Endpunkten direkt nach einem 202 bedeutet, dass die Nachricht noch nicht sichtbar ist. Versuchen Sie es nach einem kurzen Moment erneut.

Sicheres erneutes Senden

Batch-Versand

Abrechnung

Nächste Schritte

• E-Mail-Templates: Templates erstellen und veröffentlichen, die Sie hier versenden
• Kategorien: Wie marketing und transactional das Unterdrückungsverhalten ändern
• Unterdrückungen: An wen wir nicht zustellen und warum
• Zeitgesteuerter Versand: Zu einem späteren Zeitpunkt mit scheduled_at zustellen
• Test-Sandbox: Sandbox-Empfänger und Versand vor der Verifizierung
• API-Referenz: Die vollständigen Request- und Response-Schemas