Skip to content

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 ​

EndpunktWas er tut
POST /v1/mailing/sendReiht einen Versand mit dem Inhalt aus der Anfrage ein
POST /v1/mailing/send-templateReiht 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ängers

Eine 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:

statusHTTPBedeutung
success200Jeder Empfänger wurde angenommen
warning200Einige angenommen, einige abgelehnt; prüfe rejected_recipients
error400Kein 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:

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:

CodeBedeutung
1412Kein gültiger Empfänger gefunden
1413Mehr als 50 gültige Empfänger in einer Anfrage
1417Monatliches E-Mail-Kontingent aufgebraucht
1418Limit für zusätzliche E-Mails erreicht
1419Ungültige Validierungsoptionen
1421Stündliches oder tägliches Sendelimit erreicht (HTTP 429). Siehe Sendelimits
1422Die Nachricht allein überschreitet das stündliche oder tägliche Sendelimit (HTTP 400). Teile sie in kleinere Nachrichten auf

Built with VitePress