POST /mailing/send-template
Reiht eine neue E-Mail-Anfrage mit einer bestehenden Vorlage ein.
Überblick
Nutze diesen Endpunkt, um eine E-Mail mit einer in Mailiqo gespeicherten Vorlage zu senden. Die für den Versand gewählte Version der Vorlage liefert Betreff, HTML-Körper und Textkörper. Die Empfänger werden genauso verarbeitet wie bei POST /mailing/send.
Platzhalter in Vorlagen verwenden die Syntax . Nicht vorhandene Variablen werden durch einen leeren String ersetzt, und Variablen, die in der Vorlage nicht vorkommen, werden ignoriert.
Endpunkt
POST /v1/mailing/send-templatecurl -X POST https://api.mailiqo.com/v1/mailing/send-template \
-H "X-API-KEY: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"template_uuid": "7e9c6c60-8a98-4c10-9d5e-xxxxxxxx",
"from": "[email protected]",
"to": "[email protected]",
"variables": {"first_name": "Jane"}
}'Anfragekörper
Der Anfragekörper muss als JSON gesendet werden.
Pflichtfelder
| Feld | Typ | Pflicht | Beschreibung |
|---|---|---|---|
template_uuid | string | Ja | UUID der zu verwendenden Vorlage. |
from | string (email) | Ja | Absenderadresse. |
to | mixed | Ja | Hauptempfänger. Siehe Empfängerformat unten. |
Optionale Felder
| Feld | Typ | Pflicht | Beschreibung |
|---|---|---|---|
cc | mixed | Nein | Empfänger in Kopie. |
bcc | mixed | Nein | Empfänger in Blindkopie. |
variables | object | Nein | Werte, mit denen die Platzhalter der Vorlage ersetzt werden. |
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
Funktioniert genau wie bei POST /mailing/send. Standardmäßig gilt die Konfiguration der Absenderdomain; das Objekt validation verschärft sie nur für diese Anfrage:
{
"template_uuid": "7e9c6c60-8a98-4c10-9d5e-xxxxxxxx",
"from": "[email protected]",
"to": "[email protected]",
"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, und block ergänzt nur, was die Domain ohnehin blockiert. Deshalb akzeptiert mode kein never. Ein unbekannter Wert liefert 400 mit Code 1419.
Die vollständige Erklärung steht unter Empfängervalidierung.
Empfängerformat
to, cc und bcc verwenden dieselben Formate wie in POST /mailing/send dokumentiert.
Variablenformat
{
"first_name": "Jane",
"company_name": "Acme"
}Diese Werte können von Platzhaltern wie {{first_name}} und {{company_name}} verwendet werden.
Beispielanfrage
{
"template_uuid": "7e9c6c60-8a98-4c10-9d5e-xxxxxxxx",
"from": "[email protected]",
"to": [
{
"name": "Jane Doe",
"email": "[email protected]"
}
],
"variables": {
"first_name": "Jane",
"company_name": "Acme"
},
"attachments": [
{
"filename": "invoice.pdf",
"content_base64": "JVBERi0xLjQKJ...",
"content_type": "application/pdf"
}
]
}Beispiel einer erfolgreichen Antwort (status = success)
{
"status": "success",
"data": {
"uuid": "0c4ab8dc-0df4-4ef6-89ea-53ee4a8e1a3f",
"sent_to": [
{
"name": "Jane Doe",
"email": "[email protected]"
}
],
"rejected_recipients": []
}
}Beispiel einer Fehlerantwort
{
"status": "error",
"error": {
"code": "1416",
"message": "Email template not found.",
"details": {}
}
}HTTP-Antworten
| Status | Bedeutung |
|---|---|
200 | Anfrage verarbeitet. |
400 | Ungültige Anfrage oder Validierungsfehler. |
401 | Authentifizierung fehlgeschlagen oder Anfrage nicht autorisiert. |
404 | Vorlage nicht gefunden. |
409 | Die Vorlage hat keine veröffentlichte Version (1420). |
429 | Sendelimit erreicht (1421). Warte die Sekunden aus dem Retry-After-Header, bevor du erneut sendest. Siehe Sendelimits. |
500 | Interner Serverfehler. |
Hinweise
- Die Vorlage liefert Betreff und Inhalt des Körpers.
- Die Zustellung erfolgt asynchron, nachdem die Anfrage angenommen wurde.
- Angenommene und abgelehnte Empfänger folgen demselben Antwortformat wie bei
POST /mailing/send.
Verwandte Endpunkte
POST /mailing/send— ohne 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
