Skip to content

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 ​

http
POST /v1/mailing/send
bash
curl -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 ​

FeldTypPflichtBeschreibung
fromstring (email)JaAbsenderadresse.
subjectstringJaBetreff der E-Mail.
tomixedJaHauptempfänger. Siehe Empfängerformat unten.
body_html oder body_txtstringJaMindestens eines davon ist Pflicht. Inhalt des E-Mail-Körpers.

Optionale Felder ​

FeldTypPflichtBeschreibung
body_htmlstringNeinInhalt des Körpers als HTML.
body_txtstringNeinInhalt des Körpers als reiner Text.
ccmixedNeinEmpfänger in Kopie. Siehe Empfängerformat unten.
bccmixedNeinEmpfänger in Blindkopie. Siehe Empfängerformat unten.
attachmentsarrayNeinListe von Anhängen.
force_validationbooleanNeinFü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
validationobjectNeinPasst 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:

json
{
  "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"]
  }
}
FeldWerteBeschreibung
modeunknown_only, alwaysWann das Postfach des Empfängers abgefragt wird
levelpreventive, restrictiveWie anspruchsvoll die Prüfung ist
blockListe aus catch_all, risky, unknownZweifelhafte 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:

json
{
  "name": "John Doe",
  "email": "[email protected]"
}
json
[
  {
    "name": "John Doe",
    "email": "[email protected]"
  },
  {
    "name": "Jane Doe",
    "email": "[email protected]"
  }
]

Anhangsformat ​

Jeder Anhang unterstützt folgende Felder:

FeldTypPflichtBeschreibung
filenamestringJaDateiname.
content_base64stringJaDateiinhalt, base64-kodiert.
content_typestringNeinMIME-Typ der Datei.

Beispielanfrage ​

json
{
  "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.

json
{
  "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.

json
{
  "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.

json
{
  "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 ​

FeldTypBeschreibung
statusstringsuccess oder warning
data.uuidstringFür die eingereihte E-Mail-Anfrage erzeugte UUID
data.sent_toarrayListe der angenommenen Empfänger
data.rejected_recipientsarrayListe 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 ​

FeldTypBeschreibung
emailstringAbgelehnte E-Mail-Adresse
namestring/nullName des Empfängers, falls angegeben
reasonstringMaschinenlesbarer Ablehnungsgrund

Fehler-Wrapper ​

FeldTypBeschreibung
statusstringImmer error
error.codestringAPI-Fehlercode
error.messagestringÜbersetzte Fehlermeldung
error.details.sent_toarrayImmer leer, wenn kein Empfänger angenommen wurde
error.details.rejected_recipientsarrayAbgelehnte Empfänger mit Ablehnungsgrund

HTTP-Antworten ​

StatusBedeutung
200Anfrage verarbeitet. Wurden alle Empfänger angenommen, liefert der Wrapper status=success; wurden einige abgelehnt, liefert er status=warning.
400Ungültige Anfrage oder Validierungsfehler. Ist kein Empfänger gültig, wird error.details.rejected_recipients zurückgegeben.
401Authentifizierung fehlgeschlagen oder Anfrage nicht autorisiert.
429Sendelimit erreicht (1421). Warte die Sekunden aus dem Retry-After-Header, bevor du erneut sendest. Siehe Sendelimits.
500Interner 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_html und body_txt werden 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 ​

Siehe auch ​

Built with VitePress