Zum Inhalt springen
Alpha auf Einladung. Funktionen und Grenzen können sich durch unsere Testerfahrungen ändern.

API-Referenz

Basis-URL: https://api.weneed.email. Jede Anfrage authentifizieren Sie mit Authorization: Bearer <API-Schlüssel>.

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.

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

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.

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.

Ü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.

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.

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.