# E-Mail senden

> Senden Sie E-Mails mit POST /emails, mit Regeln für den Absender, Empfängern, Inhalt, Vorlagen, Tracking, der Antwort, Webhook-Events und allen Fehlercodes.

Diese Anleitung erklärt jeden Teil einer Anfrage an `POST /emails` und was Emailit damit macht, von der Absenderadresse bis zu den Fehlern, die Sie zurückbekommen können. Die vollständige Parameterreferenz finden Sie unter [E-Mail senden](/de/docs/api-reference/emails/send/) in der API-Referenz.

## Voraussetzungen

- Eine verifizierte Versanddomain in Ihrem Workspace. Siehe [Versanddomain hinzufügen](/de/docs/domains/add-a-domain/).
- Ein API-Schlüssel mit dem Scope **Full Access** oder **Sending Only**. Siehe [API-Schlüssel](/de/docs/developers/api-keys/).
- Produktionszugang, wenn Sie an andere Personen als die Mitglieder Ihres Workspace senden. Siehe [Produktionszugang](/de/docs/workspaces/production-access/).
- Genug Credits für jeden Empfänger (je 1 Credit).

## Einfache E-Mail senden

**cURL**

```bash
curl https://api.emailit.com/v2/emails \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "Acme Billing <billing@acme.com>",
    "to": ["ada@example.com", "Grace Hopper <grace@example.com>"],
    "cc": "accounts@example.com",
    "reply_to": "support@acme.com",
    "subject": "Your invoice for October",
    "html": "<p>Your invoice is ready.</p>",
    "text": "Your invoice is ready."
  }'
```

**Node.js**

```javascript
import { Emailit } from '@emailit/node';

const emailit = new Emailit(process.env.EMAILIT_API_KEY);

const email = await emailit.emails.send({
  from: 'Acme Billing <billing@acme.com>',
  to: ['ada@example.com', 'Grace Hopper <grace@example.com>'],
  cc: 'accounts@example.com',
  reply_to: 'support@acme.com',
  subject: 'Your invoice for October',
  html: '<p>Your invoice is ready.</p>',
  text: 'Your invoice is ready.',
});
```

**Python**

```python
import os
from emailit import EmailitClient

client = EmailitClient(os.environ["EMAILIT_API_KEY"])

email = client.emails.send({
    "from": "Acme Billing <billing@acme.com>",
    "to": ["ada@example.com", "Grace Hopper <grace@example.com>"],
    "cc": "accounts@example.com",
    "reply_to": "support@acme.com",
    "subject": "Your invoice for October",
    "html": "<p>Your invoice is ready.</p>",
    "text": "Your invoice is ready.",
})
```

**PHP**

```php
$emailit = Emailit::client(getenv('EMAILIT_API_KEY'));

$email = $emailit->emails()->send([
    'from' => 'Acme Billing <billing@acme.com>',
    'to' => ['ada@example.com', 'Grace Hopper <grace@example.com>'],
    'cc' => 'accounts@example.com',
    'reply_to' => 'support@acme.com',
    'subject' => 'Your invoice for October',
    'html' => '<p>Your invoice is ready.</p>',
    'text' => 'Your invoice is ready.',
]);
```

## Absenderadresse festlegen

`from` ist erforderlich und nimmt eine Adresse in einer dieser Formen an:

- `billing@acme.com`
- `Acme Billing <billing@acme.com>` oder mit Anführungszeichen `"Acme, Inc." <billing@acme.com>`

Die Domain nach dem `@` muss eine verifizierte Versanddomain im selben Workspace sein:

- **Der Abgleich ist exakt.** Domains werden ohne Beachtung der Groß-/Kleinschreibung verglichen, aber `mail.acme.com` und `acme.com` sind unterschiedliche Domains. Fügen Sie jede Subdomain hinzu, von der Sie senden, und verifizieren Sie sie.
- **Jeder lokale Teil funktioniert.** Sie brauchen kein Postfach für `billing@` oder `no-reply@`.
- **Domains in Prüfung können nicht senden.** Eine Domain, die noch auf die Prüfung wartet (**Pending verification**), gilt als nicht verifiziert.
- **Beschränkte Schlüssel bleiben bei ihrer Domain.** Ein auf eine Domain beschränkter Schlüssel mit **Sending Only** kann nur von dieser Domain senden.
- **Pausierte Domains sind blockiert.** Hat die [Versandgesundheit](/de/docs/deliverability/sending-health/) die Domain pausiert, werden Versände von ihr abgelehnt, bis die Pause aufgehoben ist.

## Empfänger hinzufügen

`to` ist erforderlich. `cc` und `bcc` sind optional. Jedes Feld akzeptiert einen String oder ein Array von Strings, mit oder ohne Anzeigenamen, und fasst bis zu 50 Adressen. Ein String kann mehrere durch Kommas getrennte Adressen enthalten; verwenden Sie ein Array, wenn ein Anzeigename selbst ein Komma enthält.

Emailit entfernt Duplikate über `to`, `cc` und `bcc` hinweg (ohne Beachtung der Groß-/Kleinschreibung) und erstellt dann **eine E-Mail pro eindeutigem Empfänger**, jede mit eigener `em_`-ID. Jede Kopie trägt dieselben Header `To` und `Cc`, sodass Empfänger die Konversation wie gewohnt sehen, und `Bcc`-Empfänger erscheinen nie in den Headern einer Kopie.

Hat eine Anfrage mehr als einen Empfänger, enthält die Antwort eine Zuordnung `ids` von Empfänger zu E-Mail-ID. `id` ist die E-Mail des ersten Empfängers.

```json
{
  "object": "email",
  "id": "em_33VtK8mRq1xZp7LwN4cY2bHsDfa",
  "ids": {
    "ada@example.com": "em_33VtK8mRq1xZp7LwN4cY2bHsDfa",
    "grace@example.com": "em_33VtK8nB5rTq0YxW3mJk9PdLsUe",
    "accounts@example.com": "em_33VtK8nQ2wErT6yU8iOp4AsDf7g"
  }
}
```

Jeder Empfänger kostet 1 Credit und zählt zu Ihren [Rate Limits](/de/docs/api-reference/rate-limits/). Ein Empfänger mit einer [Sperrung](/de/docs/suppressions/) vom Typ `recipient` wird angenommen und dann als `suppressed` markiert, statt zugestellt zu werden.

## Inhalt schreiben

| Feld | Regeln |
| --- | --- |
| `subject` | Erforderlich, sofern keine Vorlage einen liefert. Nicht-ASCII-Zeichen werden für Sie kodiert. |
| `html` | Der HTML-Inhalt. Sie brauchen `html`, `text` oder beides, sofern keine Vorlage sie liefert. |
| `text` | Der Nur-Text-Inhalt. Senden Sie ihn zusätzlich zu `html`: Manche Clients und Spamfilter bevorzugen Nachrichten mit beidem. |
| `reply_to` | Ein String oder ein Array von Adressen, an die Antworten gehen sollen. |

Nennt `reply_to` dieselbe Adresse wie `from`, entfernt Emailit den Header `Reply-To`, weil er nichts beiträgt und manche Spamfilter ihn negativ bewerten.

## Mit einer Vorlage senden

Setzen Sie `template` auf einen Alias einer Vorlage oder eine `tem_`-ID und übergeben Sie `variables` für die [Temple](/de/docs/templates/temple/)-Platzhalter darin.

- **Ein Alias** sendet die Version, die für diesen Alias aktuell veröffentlicht ist. Ist keine Version veröffentlicht, schlägt die Anfrage mit `404` fehl.
- **Eine `tem_`-ID** sendet genau diese Version, ob veröffentlicht oder nicht. Damit testen Sie eine Entwurfsversion, bevor Sie sie veröffentlichen.

Felder in der Anfrage haben Vorrang vor der Vorlage: Ein `subject`, `html` oder `text`, das Sie senden, ersetzt den Wert der Vorlage. Senden Sie kein `reply_to`, wird die Reply-To-Adresse der Vorlage verwendet. `from` ist in der Anfrage immer erforderlich. Wie das Veröffentlichen funktioniert, erfahren Sie unter [Vorlagenversionen](/de/docs/templates/versions/).

**cURL**

```bash
curl https://api.emailit.com/v2/emails \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "Acme <hello@acme.com>",
    "to": "ada@example.com",
    "template": "welcome-email",
    "variables": {
      "first_name": "Ada",
      "plan": "Pro",
      "activation_url": "https://acme.com/activate?token=8f3k2"
    }
  }'
```

**Node.js**

```javascript
const email = await emailit.emails.send({
  from: 'Acme <hello@acme.com>',
  to: 'ada@example.com',
  template: 'welcome-email',
  variables: {
    first_name: 'Ada',
    plan: 'Pro',
    activation_url: 'https://acme.com/activate?token=8f3k2',
  },
});
```

**Python**

```python
email = client.emails.send({
    "from": "Acme <hello@acme.com>",
    "to": "ada@example.com",
    "template": "welcome-email",
    "variables": {
        "first_name": "Ada",
        "plan": "Pro",
        "activation_url": "https://acme.com/activate?token=8f3k2",
    },
})
```

**PHP**

```php
$email = $emailit->emails()->send([
    'from' => 'Acme <hello@acme.com>',
    'to' => 'ada@example.com',
    'template' => 'welcome-email',
    'variables' => [
        'first_name' => 'Ada',
        'plan' => 'Pro',
        'activation_url' => 'https://acme.com/activate?token=8f3k2',
    ],
]);
```

`variables` funktioniert auch ohne Vorlage: Emailit rendert Temple-Platzhalter in `subject`, `html` und `text`, die Sie direkt mitsenden.

## Tracking steuern

Standardmäßig folgt jede E-Mail den Einstellungen **Track loads** und **Track clicks** ihrer Versanddomain. Überschreiben Sie sie pro E-Mail mit `tracking`:

- `"tracking": true` oder `false` aktiviert oder deaktiviert sowohl das Tracking von Ladevorgängen (Öffnungen) als auch das Klick-Tracking.
- `"tracking": { "loads": true, "clicks": false }` legt beides getrennt fest.

Tracking funktioniert nur, wenn der Tracking-CNAME der Domain verifiziert ist. Ohne ihn wird die E-Mail ohne Tracking gesendet, und die Anfrage ist trotzdem erfolgreich. Das Objekt `tracking` in der Antwort zeigt die tatsächlich angewendeten Einstellungen. Siehe [Öffnungs- und Klick-Tracking](/de/docs/tracking/).

## Header und Metadaten hinzufügen

Verwenden Sie `headers` für eigene E-Mail-Header wie `List-Unsubscribe` und `meta` für Ihre eigenen Schlüssel-Wert-Paare aus Strings. Emailit speichert `meta` mit der E-Mail und nimmt es in Webhook-Events auf. Siehe [Header und Metadaten](/de/docs/email-api/headers-and-metadata/).

Wie Sie Dateien anhängen, den Versand planen oder Wiederholungen sicher machen, erfahren Sie unter [Anhänge](/de/docs/email-api/attachments/), [Planung](/de/docs/email-api/scheduling/) und [Idempotenz](/de/docs/email-api/idempotency/).

## Antwort lesen

Eine erfolgreiche Anfrage gibt `200` zurück:

| Feld | Beschreibung |
| --- | --- |
| `object` | Immer `email`. |
| `id` | Die `em_`-ID der E-Mail des ersten Empfängers. |
| `ids` | Zuordnung von Empfängeradresse zu E-Mail-ID. Nur vorhanden, wenn es mehr als einen Empfänger gibt. |
| `token` | Internes Token der ersten E-Mail, das auch in ihrer Message-ID verwendet wird. |
| `message_id` | Der Header `Message-ID` der ersten E-Mail, in der Form `<token@your-domain>`. |
| `from` | Die Absenderadresse, wie Sie sie gesendet haben. |
| `to` | Die Adressen in `to`, ohne Anzeigenamen. |
| `cc`, `bcc` | Die Adressen in `cc` und `bcc`. Nur vorhanden, wenn Sie sie gesendet haben. |
| `subject` | Der endgültige Betreff, nach dem Rendern der Vorlage. |
| `status` | `accepted` oder `scheduled`, wenn die E-Mail einen zukünftigen Sendezeitpunkt hat. |
| `scheduled_at` | Der Sendezeitpunkt im Format ISO 8601 oder `null`. |
| `created_at` | Zeitpunkt der Erstellung der E-Mail. |
| `tracking` | Die angewendeten Einstellungen `loads` und `clicks`. |

Speichern Sie die `id` (oder die Zuordnung `ids`), damit Sie spätere Webhook-Events zuordnen und die E-Mail mit [E-Mail abrufen](/de/docs/api-reference/emails/get/) nachschlagen können.

## Events

Die E-Mail jedes Empfängers löst eigene Events aus:

1. [`email.accepted`](/de/docs/webhooks/events/email/accepted/) direkt nach der Anfrage oder [`email.scheduled`](/de/docs/webhooks/events/email/scheduled/), wenn sie einen zukünftigen Sendezeitpunkt hat.
2. Zustell-Events, während die E-Mail die Zustellung durchläuft: [`email.delivered`](/de/docs/webhooks/events/email/delivered/), [`email.attempted`](/de/docs/webhooks/events/email/attempted/) (vorübergehender Fehler, wird erneut versucht), [`email.bounced`](/de/docs/webhooks/events/email/bounced/), [`email.failed`](/de/docs/webhooks/events/email/failed/), [`email.rejected`](/de/docs/webhooks/events/email/rejected/) oder [`email.suppressed`](/de/docs/webhooks/events/email/suppressed/). Eine zur Prüfung zurückgehaltene E-Mail löst `email.held` aus.
3. Engagement-Events bei aktiviertem Tracking: [`email.loaded`](/de/docs/webhooks/events/email/loaded/) und [`email.clicked`](/de/docs/webhooks/events/email/clicked/). Spam-Meldungen lösen [`email.complained`](/de/docs/webhooks/events/email/complained/) aus.

Was die einzelnen Status bedeuten, erfahren Sie unter [E-Mail-Status](/de/docs/logs/email-statuses/).

## Fehler

Validierungsfehler geben eine Liste aller gefundenen Probleme zurück:

```json
{
  "error": "Validation failed",
  "validation_errors": [
    "Missing required field: subject",
    "Invalid to email address at index 1: grace@"
  ]
}
```

| Status | `error` | Ursache | Lösung |
| --- | --- | --- | --- |
| `400` | `Validation failed` | Ein erforderliches Feld fehlt, eine Adresse ist fehlerhaft, ein Feld hat mehr als 50 Empfänger oder ein Anhang ist ungültig. | Beheben Sie jeden Eintrag in `validation_errors`. |
| `400` | `Invalid Idempotency-Key` | Der Header `Idempotency-Key` hat ein ungültiges Format. | Verwenden Sie 1–256 Buchstaben, Ziffern, `-` oder `_`. Siehe [Idempotenz](/de/docs/email-api/idempotency/). |
| `401` | `Unauthorized` | Der API-Schlüssel fehlt oder ist ungültig. | Senden Sie `Authorization: Bearer` mit einem aktuellen Schlüssel. |
| `402` | `Insufficient credits` | Der Workspace kann nicht für alle Empfänger bezahlen. | [Kaufen Sie Credits](/de/docs/billing/credits/) oder aktivieren Sie die [automatische Aufladung](/de/docs/billing/auto-refill/). |
| `403` | `Workspace not verified` | Der Workspace ist im Sandbox-Modus, und ein Empfänger ist kein Mitglied des Workspace. `code` ist `unverified_workspace_recipient`, und `blocked_recipients` listet die Adressen auf. | [Beantragen Sie Produktionszugang](/de/docs/workspaces/production-access/) oder testen Sie mit den Adressen der Mitglieder. |
| `403` | `Domain not authorized` | Der API-Schlüssel ist auf eine andere Versanddomain beschränkt. | Senden Sie von der Domain des Schlüssels oder verwenden Sie einen Schlüssel ohne Domain-Beschränkung. |
| `403` | `Domain paused` | Die Versandgesundheit hat die From-Domain pausiert. | Siehe [Versandgesundheit](/de/docs/deliverability/sending-health/). |
| `404` | `Template not found` | Der Alias hat keine veröffentlichte Version, oder die `tem_`-ID existiert in diesem Workspace nicht. | Veröffentlichen Sie eine Version oder prüfen Sie die ID. |
| `409` | `Idempotency key in progress` | Eine andere Anfrage mit demselben Schlüssel läuft noch. | Warten Sie und wiederholen Sie die Anfrage dann mit demselben Schlüssel. |
| `413` | `Message too large` | Die kodierte Nachricht ist größer als 40 MB. | Senden Sie weniger oder kleinere Anhänge oder verlinken Sie große Dateien. |
| `422` | `Domain not verified` | Die From-Domain ist keine verifizierte Versanddomain in diesem Workspace. | Verifizieren Sie die Domain oder prüfen Sie auf eine Subdomain oder einen Tippfehler. |
| `422` | `Attachment error` | Eine Anhang-URL konnte nicht heruntergeladen werden oder ist größer als 25 MB. | Siehe [Anhänge](/de/docs/email-api/attachments/). |
| `429` | `Rate limit exceeded` oder `Daily limit exceeded` | Sie haben das Versandlimit pro Sekunde oder pro Tag überschritten. | Warten Sie die in `retry-after` angegebenen Sekunden ab oder beantragen Sie ein höheres Limit. |
| `503` | `Idempotency unavailable` | Der Idempotenzspeicher war nicht erreichbar. | Wiederholen Sie die Anfrage mit demselben Schlüssel. |

Ein gesperrter Workspace erhält bei jedem Versand `403` mit `Workspace is suspended`. Das allgemeine Fehlerformat finden Sie unter [Fehler](/de/docs/api-reference/errors/).

## Siehe auch

- [E-Mail senden](/de/docs/api-reference/emails/send/) in der API-Referenz
- [Vorlagen](/de/docs/templates/)
- [E-Mail-Status](/de/docs/logs/email-statuses/)
- [Webhook-Event-Typen](/de/docs/webhooks/event-types/)
- [Warum ist meine E-Mail nicht angekommen?](/de/docs/kb/email-not-delivered-checklist/)

---
Quelle: https://emailit.com/de/docs/email-api/send-email/