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,ccundbcczusammen enthalten höchstens 50 Empfänger.htmlundtext: 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.