Zum Inhalt springen
Esc
↑↓navigieren↵öffnen⌘Jvorschau
Auf dieser Seite

E-Mails

Eine E-Mail oder einen Batch senden, planen und von „angenommen“ bis „zugestellt“ verfolgen.

Eine E-Mail ist eine POST /emails-Anfrage oder eine Nachricht über das SMTP-Relay. BillionSend prüft sie, speichert sie und gibt sofort eine id zurück. Der Versand läuft im Hintergrund, ein 200 bedeutet also, dass die E-Mail angenommen, nicht dass sie zugestellt wurde.

Eine E-Mail senden

import { BillionSend } from "@billionsend/node";

const bs = new BillionSend(); // reads BILLIONSEND_API_KEY

const { data, error } = await bs.emails.send({
  from: "Acme <hello@mail.example.com>",
  to: ["success@simulator.amazonses.com"],
  subject: "Welcome",
  html: "<p>Thanks for signing up.</p>",
});

Derselbe Aufruf mit curl:

curl -X POST https://api.billionsend.com/emails \
  -H "Authorization: Bearer $BILLIONSEND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "Acme <hello@mail.example.com>",
    "to": ["success@simulator.amazonses.com"],
    "subject": "Welcome",
    "html": "<p>Thanks for signing up.</p>"
  }'
  • from: muss auf einer verifizierten Domain Ihres Teams liegen.
  • to, cc, bcc, reply_to: eine Adresse oder eine Liste. to, cc und bcc zusammen enthalten höchstens 50 Empfänger.
  • html und text: Mindestens eines ist erforderlich. Das Senden mit einer Vorlagen-ID wird nicht unterstützt. Eine Vorlage ist Inhalt, den Sie in einen Newsletter-Versand kopieren.
  • tags, headers, attachments: Die Regeln, die Anhangslimits und die Idempotenz finden Sie unter API-Grundlagen.
  • topic_id: Empfänger, die dieses Thema abbestellt haben, werden übersprungen.

Die Adresse success@simulator.amazonses.com in diesen Beispielen gehört zum Simulator: Sie schreibt niemandem, nutzen Sie sie also zum Testen.

Einen Batch senden

POST /emails/batch nimmt ein Array mit bis zu 100 E-Mails entgegen. Standardmäßig lässt eine ungültige E-Mail den gesamten Batch fehlschlagen. Mit dem Header x-batch-validation: permissive werden die gültigen akzeptiert: data listet deren IDs, und errors listet die übrigen nach Position.

Planen, ändern, abbrechen

Mit scheduled_at senden Sie später, bis zu 30 Tage im Voraus. Der Wert ist eine ISO-8601-Zeit mit Offset oder eine relative Zeit wie in 2 hours. Solange eine E-Mail geplant ist, ändert PATCH /emails/{id} ihre Zeit, und POST /emails/{id}/cancel bricht sie ab.

Eine E-Mail verfolgen

GET /emails/{id} liefert die E-Mail mit last_event, ihrem neuesten Ergebnis, und einem score aus den Zustellbarkeits-Einblicken. Im Dashboard listet E-Mails jede E-Mail auf und zeigt ihre Ereignisse in der richtigen Reihenfolge. Inhalte und Verlauf werden 30 Tage lang aufbewahrt.

Ereignis Bedeutung
email.scheduled Angenommen und wartet auf ihren Zeitpunkt.
email.sent Zur Zustellung übergeben.
email.delivered Der Server des Empfängers hat sie angenommen.
email.delivery_delayed Die Zustellung verzögert sich und wird erneut versucht.
email.bounced Der Server des Empfängers hat sie abgelehnt.
email.complained Der Empfänger hat sie als Spam markiert.
email.failed Sie konnte nicht gesendet werden. Das Ereignis nennt den Grund.
email.suppressed Sie wurde nicht gesendet, weil jeder Empfänger gesperrt oder abgemeldet ist.
email.opened, email.clicked Der Empfänger hat sie geöffnet oder einen Link angeklickt, sofern Tracking aktiv ist.

Jedes Ereignis lässt sich auch als Webhook an Sie senden.

Was einen Versand stoppt oder zurückhält

Ein Versand wird mit einem 4xx-Fehler abgelehnt, der den Grund nennt, wenn:

  • die Absenderdomain nicht verifiziert ist (422);
  • jeder Empfänger gesperrt ist (422 all_recipients_suppressed);
  • Sie das Volumen Ihres Tarifs überschritten haben (429);
  • Ihre Bounce- oder Beschwerderate den Versand pausiert hat (403 sending_paused).

Manche E-Mails werden angenommen, aber zurückgehalten und gehen später hinaus: eine neue Domain über ihrer Tagesgrenze oder E-Mails, die auf das Zurücksetzen eines Limits warten. Siehe Sendelimits. Die API und das SMTP-Relay wenden dieselben Regeln an.

War diese Seite hilfreich?