Wissensdatenbank

E-Mail-API

Eine Nachricht oder hundert pro Aufruf senden, jetzt oder später, und wiederholen, ohne doppelt zu senden.

Details

POST /emails sendet eine Nachricht und POST /emails/batch bis zu 100 voneinander unabhängige. Ein Stapel ist nie alles oder nichts: Eine falsche Adresse bei Eintrag 7 lässt Eintrag 7 scheitern, der Rest geht trotzdem raus, und die Antwort meldet jeden Eintrag einzeln.
Der Inhalt kommt aus genau einer Quelle: html und/oder text, eine gespeicherte Vorlage per ID oder Slug (fixieren Sie die Version, wenn jemand anderes den Text verantwortet) oder ein bestehender Entwurf. Bis zu 10 Tags fahren mit und werden bei jedem Abruf zurückgegeben.
scheduledAt hält eine Nachricht bis zu 365 Tage zurück, als ISO-8601-Zeitpunkt oder als Dauer wie PT1H. cancellableForSeconds gibt einem sofortigen Versand ein Rückgängig-Fenster von bis zu 900 Sekunden. Beides lässt sich bis zum Versand stornieren, und ein geplanter Versand lässt sich verschieben.
Jeder Versand trägt einen Idempotency-Key, der beansprucht wird, bevor irgendetwas rausgeht, sodass eine Wiederholung nach einem Timeout das erste Ergebnis mit Idempotency-Replayed: true zurückgibt. Derselbe Schlüssel mit anderem Inhalt wird als idempotency_key_reuse abgelehnt.
Jeder Versand hat ab der Annahme eine msg_-ID. GET /emails/{id} liest ihn, /events liefert die Spur für jeden Empfänger und /tracking die Öffnungen und Klicks.
Mit translate wird die Nachricht in der Sprache des Empfängers zugestellt. Übersetzt wird bei Annahme der Anfrage, sodass ein geplanter Versand den freigegebenen Wortlaut trägt, und eine Übersetzung, die nicht gelingt, lehnt den Versand ab, statt auf das Original zurückzufallen.
Anhänge: bis zu 20 Dateien, eingebettete insgesamt bis 5 MB. Eine größere Datei wird über die ID einer Workspace-Datei gesendet und reist als Download-Link.
Was fehlt: Es gibt noch keinen Testmodus, also stellt jeder Schlüssel wirklich zu, und der Versandeintrag kennt keinen Bounce-Status. Ein Bounce wird am Thread markiert und als Webhook email.bounced gemeldet, während GET /emails weiterhin sent zeigt.
Die Sperrliste, in den Einstellungen „Blockierte Adressen“, gibt es auch in der API. GET /suppressions liest sie mit einer Suche und einem Filter nach Grund, POST /suppressions sperrt eine Adresse von Hand, und DELETE /suppressions/{id} lässt eine wieder zu, außer einem Hard Bounce, der bleibt. SDK und MCP-Server tun dasselbe, und jede Änderung löst den Webhook suppression.added oder suppression.removed aus.