E-Mail-Versand-API
Stelle E-Mails in die Warteschlange und verfolge ihre Zustellung Empfänger für Empfänger. Es gibt zwei Wege zu senden — mit dem Inhalt in der Anfrage selbst oder mit einer gespeicherten Vorlage — und zwei Abfrage-Endpunkte, um hinterher zu erfahren, was passiert ist.
Jede Anfrage verwendet den Header X-API-KEY. Siehe Authentifizierung.
Endpunkte
| Endpunkt | Was er tut |
|---|---|
POST /v1/mailing/send | Reiht einen Versand mit dem Inhalt aus der Anfrage ein |
POST /v1/mailing/send-template | Reiht einen Versand mit einer gespeicherten Vorlage ein |
GET /v1/mailing/email-request/{uuid} | Status der Anfrage und die daraus erzeugten Nachrichten |
GET /v1/mailing/email-message/{uuid} | Zustellstatus und Validierung für einen Empfänger |
Der Versand ist asynchron
Die API nimmt die Anfrage an und reiht sie ein; sie stellt nicht sofort zu. Deshalb bedeutet eine erfolgreiche Anfrage noch keine erfolgreiche Zustellung, und das Tracking braucht zwei Schritte:
POST /v1/mailing/send -> uuid der Anfrage
GET /v1/mailing/email-request/{uuid} -> email_messages[] (eine uuid pro Empfänger)
GET /v1/mailing/email-message/{uuid} -> Status und Validierung dieses EmpfängersEine Anfrage (email_request) erzeugt eine Nachricht pro Empfänger (email_message). Zustellstatus, Öffnungen, Klicks und das Validierungsergebnis liegen auf der Nachricht, nicht auf der Anfrage.
Die drei Antwortzustände
Beide Sende-Endpunkte geben eine gekapselte Antwort zurück, die sich je nach Anzahl der angenommenen Empfänger auf drei Arten auflösen kann:
status | HTTP | Bedeutung |
|---|---|---|
success | 200 | Jeder Empfänger wurde angenommen |
warning | 200 | Einige angenommen, einige abgelehnt; prüfe rejected_recipients |
error | 400 | Kein Empfänger wurde angenommen, oder die Anfrage war ungültig |
Prüfe immer rejected_recipients
Ein 200 garantiert nicht, dass alle deine Empfänger durchgekommen sind. Mit status = warning wird die Anfrage nur für die angenommenen Empfänger eingereiht, und die verworfenen kommen mit ihrem Grund in data.rejected_recipients zurück. Wird keiner angenommen, steht dieselbe Liste in error.details.rejected_recipients.
Empfänger
to, cc und bcc akzeptieren dieselben vier Formate (eine einzelne Adresse, eine Liste, ein Objekt mit Namen oder eine Liste von Objekten), dokumentiert unter Empfängerformat.
Erlaubt sind maximal 50 gültige Empfänger pro Anfrage. Werden nach der Vorverarbeitung mehr als 50 angenommen, wird die Anfrage abgelehnt.
Empfängervalidierung
Vor der Zustellung prüft Mailiqo, dass jeder Empfänger existiert und erreichbar ist. Das wird pro Domain konfiguriert, und jeder Versand kann es verschärfen mit dem Objekt validation:
- Validierung für diesen Versand — der Parameter, mit Beispiel
- Empfängervalidierung — was geprüft wird und wie es konfiguriert ist
- E-Mail-Validierungs-API — Adressen prüfen, ohne ihnen etwas zu senden
Das Ergebnis pro Empfänger kommt nicht in der Sendeantwort zurück: die erweiterte Prüfung läuft, nachdem dir geantwortet wurde. Du liest es im Block validation von GET /email-message/{uuid}.
Fehler
Die Versandcodes reichen von 1400 bis 1422 und sind in der Fehlerreferenz aufgeführt. Die häufigsten:
| Code | Bedeutung |
|---|---|
1412 | Kein gültiger Empfänger gefunden |
1413 | Mehr als 50 gültige Empfänger in einer Anfrage |
1417 | Monatliches E-Mail-Kontingent aufgebraucht |
1418 | Limit für zusätzliche E-Mails erreicht |
1419 | Ungültige Validierungsoptionen |
1421 | Stündliches oder tägliches Sendelimit erreicht (HTTP 429). Siehe Sendelimits |
1422 | Die Nachricht allein überschreitet das stündliche oder tägliche Sendelimit (HTTP 400). Teile sie in kleinere Nachrichten auf |
