API-Referenz
Basis-URL: https://api.weneed.email. Jede Anfrage authentifizieren Sie mit
Authorization: Bearer <API-Schlüssel>.
Endpunkte
Abschnitt betitelt „Endpunkte“| Methode | Pfad | Zweck |
|---|---|---|
POST |
/v1/emails |
Nachricht einliefern. Verlangt Idempotency-Key. |
GET |
/v1/emails |
Nachrichten der letzten 30 Tage auflisten, neueste zuerst. Braucht Leserecht. |
GET |
/v1/emails/{id} |
Status, Grund und Verlauf einer Nachricht lesen. Braucht Leserecht. |
POST |
/v1/emails/{id}/cancel |
Eine noch nicht gesendete Nachricht abbrechen. |
GET |
/v1/usage |
Verbrauch und verbleibendes Kontingent lesen. |
GET |
/v1/suppressions?address= |
Prüfen, ob eine Adresse gesperrt ist. Braucht suppressions:read. |
Schlüssel sind entweder nur Senden oder Senden, E-Mail-Metadaten lesen und Verbrauch lesen.
Leseschlüssel, die ab jetzt ausgestellt werden, können auch gesperrte Empfänger prüfen
(suppressions:read); bestehende Schlüssel behalten die Rechte, mit denen sie ausgestellt wurden.
Mit einem Nur-Senden-Schlüssel können Sie keinen Status abfragen; nutzen Sie dafür das Dashboard.
Schlüssel haben standardmäßig kein Ablaufdatum. Für vorübergehenden Zugriff können Sie eine begrenzte Gültigkeit wählen. Sie können Schlüssel jederzeit in Control ersetzen oder widerrufen. Siehe
API-Schlüssel und SMTP-Zugänge.
Request-Body für POST /v1/emails
Abschnitt betitelt „Request-Body für POST /v1/emails“| Feld | Pflicht | Hinweis |
|---|---|---|
stream_id |
ja | UUID, die beim Zugang angezeigt wird |
from |
ja | { email, name? }; muss Ihrem freigegebenen Absender entsprechen |
to |
ja | Genau ein { email, name? } |
subject |
ja | Bis zu 998 Zeichen |
text / html |
mindestens eines | Inhalt |
reply_to |
nein | Genau ein { email, name? } |
expires_at |
nein | ISO-8601-Zeitpunkt; danach kein Versand |
tags |
nein | Bis zu 10 Schlüssel (1–64 Zeichen), Werte bis 256 Zeichen |
Nachrichten auflisten: GET /v1/emails
Abschnitt betitelt „Nachrichten auflisten: GET /v1/emails“Abfrageparameter, alle optional:
| Parameter | Hinweis |
|---|---|
state |
Ein Einlieferungszustand. |
outcome |
Ein Empfängerergebnis. |
transport |
api, smtp oder unknown. |
from, to |
UTC-Zeitpunkte wie 2026-10-01T00:00:00Z; from einschließlich, to ausschließlich. |
id |
Eine Nachrichten-ID. |
tag |
Genau schlüssel:wert, etwa order:1234. Der Schlüssel endet am ersten Doppelpunkt. |
cause |
Der Ursachencode des aktuellen Zustands. |
limit |
1–100, Standard 25. |
cursor |
Der next_cursor der vorigen Seite. |
Jeder Eintrag hat id, accepted_at, submission_state, recipient_outcome, transport,
simulated und tags (null, wenn historische Tags nicht gespeichert wurden). Die Liste liefert nie Betreff, Inhalt oder Empfänger, und eine Suche nach
Empfängern gibt es nicht. Auf der letzten Seite ist next_cursor null. Ein Cursor funktioniert
nur mit demselben Schlüssel und denselben Filtern; sonst kommt 400.
Eine Nachricht lesen: GET /v1/emails/{id}
Abschnitt betitelt „Eine Nachricht lesen: GET /v1/emails/{id}“Die bisherigen Felder bleiben unverändert. Danach folgen:
| Feld | Bedeutung |
|---|---|
tags |
Die gesendeten Tags oder null, wenn historische Tags nicht gespeichert wurden. |
reason |
Warum die Nachricht in ihrem aktuellen Zustand ist: code, category, retry oder null. |
attempts |
Die neuesten 25 Versandversuche: number, created_at, kind, code, route und route_label (ohne Aufzeichnung null). |
attempt_total |
Wie viele Versuche es insgesamt gibt. |
feedback |
Eingegangene Zustellmeldungen: action, erweiterter status, occurred_at. |
current_blockers |
Solange die Nachricht noch gesendet werden kann: was sie gerade aufhält, als Codes. |
trace |
Beobachtete Routenschritte. Fehlende Beobachtungen belegen keinen Fehler und keinen ausgelassenen Schritt. |
trace_limits |
Lücken in gespeicherten Nachweisen; ein fehlendes Ereignis ist kein Zustellergebnis. |
Die timeline ist standardmäßig vollständig. Zum Blättern übergeben Sie timeline_limit (1–100)
und danach den timeline_cursor aus timeline_next_cursor.
Eine Adresse prüfen: GET /v1/suppressions
Abschnitt betitelt „Eine Adresse prüfen: GET /v1/suppressions“Übergeben Sie genau eine Adresse. Die Antwort enthält address, suppressed, reason
(hard_bounce, complaint oder platform), since (null, wenn nicht erfasst) und
source_email_id (nur, wenn die Nachricht zu diesem Projekt gehört). Eine Liste oder einen Export
gibt es nicht. Siehe Bounces und gesperrte Adressen.
Antwortcodes
Abschnitt betitelt „Antwortcodes“| Code | Bedeutung |
|---|---|
202 |
Gespeichert und eingereiht (oder als gesperrt protokolliert). Noch nicht zugestellt. |
400 |
Fehlerhafte Anfrage. |
401 |
Schlüssel fehlt, ist falsch oder abgelaufen. |
403 |
Der Schlüssel darf das nicht, etwa falscher Absender oder fehlendes Recht. |
404 |
Nachricht oder Stream für diesen Schlüssel nicht gefunden. |
409 |
Konflikt, etwa ein Idempotency-Key mit anderem Inhalt. |
413 |
Nachricht zu groß. |
422 |
Gültiges JSON, das nicht angenommen werden kann, etwa ein nicht freigegebener Absender. |
429 |
Ratenlimit oder Kontingent erreicht. error.reason nennt das Limit; siehe unten. |
503 |
Vorübergehend nicht verfügbar oder Ergebnis unklar. Mit demselben Key und Body wiederholen. |
Jeder Fehler-Body enthält error.code und error.message. Die Seite
API-Fehler listet jeden Code mit Bedeutung und mit der Angabe, ob eine
Wiederholung Erfolg haben kann.
Limits und Retry-After
Abschnitt betitelt „Limits und Retry-After“Ein 429 wegen eines Versandlimits enthält error.reason und, wenn Warten hilft, einen
Retry-After-Header in Sekunden:
error.reason |
Retry-After |
|---|---|
daily_limit_reached |
Bis zur nächsten Mitternacht UTC. |
monthly_limit_reached |
Bis zum ersten Tag des nächsten Monats, UTC. |
rate_limited |
Die Länge des Ratenfensters. |
pending_limit_reached |
60 Sekunden. |
lifetime_limit_reached |
Keiner: Warten hilft nicht. Wenden Sie sich an den Support. |
service_capacity |
Bis zum nächsten Zurücksetzen des Fensters, oder keiner. |
Wiederholen Sie nach der Wartezeit mit demselben Idempotency-Key. Andere 429-Antworten behalten
Retry-After: 60.