---
title: E-Mails
description: Eine E-Mail oder einen Batch senden, planen und von „angenommen“ bis „zugestellt“ verfolgen.
seo:
  title: E-Mail-API zum Senden
ai:
  exclude: true
---

Eine E-Mail ist eine `POST /emails`-Anfrage oder eine Nachricht über das [SMTP-Relay](/docs/de/smtp). 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

```ts
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`:

```bash
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](/docs/de/concepts/domains) 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](/docs/de/concepts/templates) ist Inhalt, den Sie in einen Newsletter-Versand kopieren.
- `tags`, `headers`, `attachments`: Die Regeln, die Anhangslimits und die Idempotenz finden Sie unter [API-Grundlagen](/docs/de/api-reference/basics).
- `topic_id`: Empfänger, die dieses [Thema](/docs/de/concepts/topics) 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](/docs/de/concepts/deliverability-insights). 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](/docs/de/concepts/tracking) aktiv ist. |

Jedes Ereignis lässt sich auch als [Webhook](/docs/de/concepts/webhooks) 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](/docs/de/concepts/suppressions) 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](/docs/de/concepts/sending-limits). Die API und das SMTP-Relay wenden dieselben Regeln an.
