POST /mailing/send
Reiht eine neue E-Mail-Anfrage zur Zustellung ein.
Überblick
Nutze diesen Endpunkt, um eine einzelne E-Mail-Anfrage an Mailiqo zu übergeben. Die Anfrage wird validiert, die Empfänger werden verarbeitet, und die Nachricht wird zur asynchronen Zustellung eingereiht.
Die Antwort ist gekapselt und kann drei logische Zustände zurückgeben:
status = success: alle Empfänger wurden angenommen.status = warning: einige Empfänger wurden angenommen, andere abgelehnt.status = error: kein Empfänger konnte angenommen werden, oder es trat eine andere Validierungs-/Fehlerbedingung auf.
Endpunkt
POST /v1/mailing/sendcurl -X POST https://api.mailiqo.com/v1/mailing/send \
-H "X-API-KEY: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"from": "[email protected]",
"to": "[email protected]",
"subject": "Willkommen bei Mailiqo",
"body_html": "<p>Hallo Welt</p>"
}'Anfragekörper
Der Anfragekörper muss als JSON gesendet werden.
Pflichtfelder
| Feld | Typ | Pflicht | Beschreibung |
|---|---|---|---|
from | string (email) | Ja | Absenderadresse. |
subject | string | Ja | Betreff der E-Mail. |
to | mixed | Ja | Hauptempfänger. Siehe Empfängerformat unten. |
body_html oder body_txt | string | Ja | Mindestens eines davon ist Pflicht. Inhalt des E-Mail-Körpers. |
Optionale Felder
| Feld | Typ | Pflicht | Beschreibung |
|---|---|---|---|
body_html | string | Nein | Inhalt des Körpers als HTML. |
body_txt | string | Nein | Inhalt des Körpers als reiner Text. |
cc | mixed | Nein | Empfänger in Kopie. Siehe Empfängerformat unten. |
bcc | mixed | Nein | Empfänger in Blindkopie. Siehe Empfängerformat unten. |
attachments | array | Nein | Liste von Anhängen. |
force_validation | boolean | Nein | Führt beim Senden eine neue Prüfung für jeden Empfänger aus, ohne frühere Ergebnisse wiederzuverwenden. Entspricht validation.mode: "always" und verbraucht ein Guthaben pro geprüftem Empfänger |
validation | object | Nein | Passt die Validierung nur für diesen Versand an. Siehe Validierung für diesen Versand |
Validierung für diesen Versand
Standardmäßig gilt die Validierungskonfiguration der Absenderdomain. Braucht dieser Versand mehr Sorgfalt — eine Bestellbestätigung, ein Zurücksetzen des Passworts — füge das Objekt validation hinzu:
{
"from": "[email protected]",
"to": "[email protected]",
"subject": "Bestätige deine Bestellung",
"body_html": "<p>Danke für deinen Einkauf.</p>",
"validation": {
"mode": "always",
"level": "restrictive",
"block": ["catch_all", "risky"]
}
}| Feld | Werte | Beschreibung |
|---|---|---|
mode | unknown_only, always | Wann das Postfach des Empfängers abgefragt wird |
level | preventive, restrictive | Wie anspruchsvoll die Prüfung ist |
block | Liste aus catch_all, risky, unknown | Zweifelhafte Ergebnisse, die du für diesen Versand verwirfst |
Ein Versand kann nur verschärfen
Die Anpassung lockert nie die Domain-Konfiguration: fragt die Domain bereits bei jedem Versand ab, senkt unknown_only das nicht, und block ergänzt nur, was die Domain ohnehin blockiert. Deshalb akzeptiert mode kein never.
Ein unbekannter Wert liefert 400 mit Code 1419.
Alle drei Felder, wie sie auf die Domain-Konfiguration abgebildet werden und wie du das Ergebnis pro Empfänger liest, sind beschrieben unter Empfängervalidierung.
Empfängerformat
⚠️ Achtung: in einer einzelnen Anfrage sind maximal 50 gültige Empfänger erlaubt. Werden nach der Vorverarbeitung mehr als 50 Empfänger angenommen, wird die Anfrage abgelehnt.
to, cc und bcc akzeptieren folgende Formate:
"[email protected]"[
"[email protected]",
"[email protected]"
]{
"name": "John Doe",
"email": "[email protected]"
}[
{
"name": "John Doe",
"email": "[email protected]"
},
{
"name": "Jane Doe",
"email": "[email protected]"
}
]Anhangsformat
Jeder Anhang unterstützt folgende Felder:
| Feld | Typ | Pflicht | Beschreibung |
|---|---|---|---|
filename | string | Ja | Dateiname. |
content_base64 | string | Ja | Dateiinhalt, base64-kodiert. |
content_type | string | Nein | MIME-Typ der Datei. |
Beispielanfrage
{
"from": "[email protected]",
"subject": "Willkommen bei Mailiqo",
"body_html": "<p>Hallo Welt</p>",
"body_txt": "Hallo Welt",
"to": [
{
"name": "Jane Doe",
"email": "[email protected]"
}
],
"cc": [
"[email protected]",
"invalid@example"
],
"bcc": [],
"attachments": [
{
"filename": "invoice.pdf",
"content_base64": "JVBERi0xLjQKJ...",
"content_type": "application/pdf"
}
]
}Beispiel einer erfolgreichen Antwort (status = warning)
Tritt auf, wenn mindestens ein Empfänger angenommen und mindestens einer abgelehnt wird.
{
"status": "warning",
"data": {
"uuid": "0c4ab8dc-0df4-4ef6-89ea-53ee4a8e1a3f",
"sent_to": [
{
"name": "Jane Doe",
"email": "[email protected]"
},
{
"email": "[email protected]",
"name": null
}
],
"rejected_recipients": [
{
"email": "invalid@example",
"name": null,
"reason": "invalid_format"
}
]
}
}Beispiel einer erfolgreichen Antwort (status = success)
Tritt auf, wenn alle Empfänger angenommen werden.
{
"status": "success",
"data": {
"uuid": "0c4ab8dc-0df4-4ef6-89ea-53ee4a8e1a3f",
"sent_to": [
{
"name": "Jane Doe",
"email": "[email protected]"
}
],
"rejected_recipients": []
}
}Beispiel einer Fehlerantwort (status = error)
Kann kein Empfänger angenommen werden, liefert der Endpunkt 400 und listet die abgelehnten Empfänger in error.details auf.
{
"status": "error",
"error": {
"code": "1412",
"message": "No valid recipients found.",
"details": {
"sent_to": [],
"rejected_recipients": [
{
"email": "invalid@example",
"name": null,
"reason": "invalid_format"
}
]
}
}
}Antwortfelder
Wrapper für success/warning
| Feld | Typ | Beschreibung |
|---|---|---|
status | string | success oder warning |
data.uuid | string | Für die eingereihte E-Mail-Anfrage erzeugte UUID |
data.sent_to | array | Liste der angenommenen Empfänger |
data.rejected_recipients | array | Liste der abgelehnten Empfänger mit Ablehnungsgrund |
Zusätzliche E-Mails
Ist das in deinem Plan enthaltene Monatskontingent aufgebraucht, wird der Versand mit Fehler 1417 abgelehnt. Aktivierst du im Kundenbereich zusätzliche E-Mails, läuft der Versand über das Kontingent hinaus bis zu dem Limit, das du festlegst; ist dieses erreicht, wird er mit 1418 abgelehnt, und die genutzte Überschreitung wird mit deiner nächsten Rechnung abgerechnet.
Objekt eines abgelehnten Empfängers
| Feld | Typ | Beschreibung |
|---|---|---|
email | string | Abgelehnte E-Mail-Adresse |
name | string/null | Name des Empfängers, falls angegeben |
reason | string | Maschinenlesbarer Ablehnungsgrund |
Fehler-Wrapper
| Feld | Typ | Beschreibung |
|---|---|---|
status | string | Immer error |
error.code | string | API-Fehlercode |
error.message | string | Übersetzte Fehlermeldung |
error.details.sent_to | array | Immer leer, wenn kein Empfänger angenommen wurde |
error.details.rejected_recipients | array | Abgelehnte Empfänger mit Ablehnungsgrund |
HTTP-Antworten
| Status | Bedeutung |
|---|---|
200 | Anfrage verarbeitet. Wurden alle Empfänger angenommen, liefert der Wrapper status=success; wurden einige abgelehnt, liefert er status=warning. |
400 | Ungültige Anfrage oder Validierungsfehler. Ist kein Empfänger gültig, wird error.details.rejected_recipients zurückgegeben. |
401 | Authentifizierung fehlgeschlagen oder Anfrage nicht autorisiert. |
429 | Sendelimit erreicht (1421). Warte die Sekunden aus dem Retry-After-Header, bevor du erneut sendest. Siehe Sendelimits. |
500 | Interner Serverfehler. |
Hinweise
- Die Zustellung erfolgt asynchron, nachdem die Anfrage angenommen wurde.
- Die angenommenen Empfänger können von den übermittelten abweichen, wenn Adressen in der Vorverarbeitung abgelehnt werden.
body_htmlundbody_txtwerden in derselben Anfrage unterstützt.- Abgelehnte Empfänger werden außerdem einzeln mit ihrem Ablehnungsgrund in den für den Kunden sichtbaren Protokollen erfasst.
Verwandte Endpunkte
POST /mailing/send-template— mit einer Vorlage sendenGET /mailing/email-request/{uuid}— Status der AnfrageGET /mailing/email-message/{uuid}— Status und Validierung pro Empfänger
Siehe auch
- E-Mail-Versand-API — der gesamte Ablauf und die Antwortzustände
- Empfängervalidierung — wie sie konfiguriert wird und was geprüft wird
- E-Mail-Validierungs-API — Adressen prüfen, ohne ihnen etwas zu senden
