logoDokumentation
E-Mail
Doku-Startseite
SchnellstartAnweisungenREST APISMTPUseMarketingWebHookResources
Suchen
Deutsch
English
繁體中文
简体中文
日本語
ภาษาไทย
Español
Bahasa Indonesia
Deutsch
Français
Anmelden
REST API / Deliverlies

E-Mail-API: REST API-Endpunkte, Versandoptionen und Kalenderintegration

Zuletzt aktualisiert：almost 3 years ago

Mit der EngageLab E-Mail-API versenden Sie E-Mails, Newsletter, Kalender-Einladungen und mehr – flexibel, sicher und effizient. Diese Anleitung zeigt Ihnen alle REST API-Endpunkte, Parameter und Best Practices für den professionellen E-Mail-Versand.

API-Endpunkte

Rechenzentrum URL
Singapur https://email.api.engagelab.cc
Türkei https://emailapi-tr.engagelab.com

Stellen Sie sicher, dass das gewählte Rechenzentrum der entsprechenden Basis-URL entspricht.

Standardversand per REST API

URL

https://email.api.engagelab.cc/v1/mail/send
              
              https://email.api.engagelab.cc/v1/mail/send
Diesen Codeblock im schwebenden Fenster anzeigen

Content-Type:
Content-Type: application/json;charset=utf-8
(Stellen Sie sicher, dass der Content-Type-Header korrekt gesetzt ist, um eine reibungslose Verarbeitung zu gewährleisten.)

HTTP-Request-Methode:
POST

Request Header

Header Typ Erforderlich Beschreibung
Authorization String ja Basic base64(api_user:api_key)

Request Parameter

Parameter Typ Erforderlich Beschreibung
from string ja Absender. Beispiel: support@mail.engagelab.com oder EngageLab Team<support@mail.engagelab.com>. Soll der Produkt- oder Markenname angezeigt werden, nutzen Sie EngageLab Team<support@mail.engagelab.com>. „EngageLab Team“ ist der Absendername, <support@mail.engagelab.com> die Absenderadresse.
to array[string] ja Empfänger:innen. Bis zu 100 Adressen werden unterstützt. Beispiel: ["xjm@hotmail.com","xjm2@gmail.com"]
body object ja E-Mail-Einstellungen
custom_args object nein Optionale, vom Kunden definierte Felder (maximal 1 KB). Die Schlüssel (Keys) dürfen keinen Punkt („.“) enthalten.
request_id string nein ID dieser Versandanfrage; maximal 128 Zeichen. Ist eine Stunde lang gültig.

Body

Parameter Typ Erforderlich Beschreibung
cc array[string] nein CC. Maximal 100 Adressen. Nur bei send_mode=1 gültig.
bcc array[string] nein BCC. Maximal 100 Adressen. Nur bei send_mode=1 gültig.
reply_to array[string] nein Antwortadresse(n). Bis zu 3 Adressen; ohne Angabe wird „from“ verwendet.
subject string ja Betreff. Maximal 256 Zeichen; unterstützt Variablen und Emojis.
content object ja Inhalt der E-Mail
html string * HTML-Inhalt. Format: text/html.
text string * Text-Inhalt. Format: text/plain.
preview_text string nein Vorschau-Text. Nur in Verbindung mit HTML wirksam.
vars object nein Variablen für den Inhalt. Bis zu 1 MB; gültig bei send_mode=0 oder 1.
dynamic_vars array[object] nein Dynamische Template-Variablen (maximal 1 MB); gültig bei send_mode=0 oder 1.
label_id string nein Label-ID für diesen Versand
label_name string nein Label-Name für diesen Versand
headers object nein Header (maximal 1 KB). Siehe Hinweise für erlaubte Schlüssel.
attachments array[object] nein Anhänge. Gesamtgröße maximal 10 MB.
content (Anhang) string ja Inhalt des Anhangs (Base64-codiert; dies ist eine gängige Kodierung für Binärdaten).
filename string ja Dateiname des Anhangs, z. B. news.pdf
disposition string ja „attachment“ oder „inline“
content_id string nein Bei disposition=inline und Bilddatei erforderlich
settings object nein Sende-Einstellungen
send_mode int nein Versandmodus: 0 = einzeln; 1 = Broadcast (alle Empfänger:innen sichtbar); 2 = Versand an Adressliste. Standard: 0
return_email_id boolean nein Rückgabe der E-Mail-ID, Standard: true
sandbox boolean nein Sandbox-Modus (nur Parameterprüfung, kein Versand). Standard: false
notification boolean nein Lesebestätigung aktivieren, Standard: false. Empfangsroute erforderlich.
open_tracking boolean nein Öffnungstracking aktivieren, Standard-Systemwert. Gültig bei send_mode=0 oder 1.
click_tracking boolean nein Klicktracking aktivieren, Standard-Systemwert. Gültig bei send_mode=0 oder 1.
unsubscribe_tracking boolean nein Abmeldelink aktivieren, Standard-Systemwert. Gültig bei send_mode=0 oder 1.
unsubscribe_page_id array[int] nein Benutzerdefinierte Abmeldeseite(n), Standard-Systemwert. Gültig bei send_mode=0 oder 1.

Hinweise

  1. Bei send_mode=2 ist der Wert von „to“ ein Adresslisten-Kürzel (maximal 5 Einträge). Die Parameter cc und bcc sind in diesem Fall ungültig.

  2. HTML und Text dürfen nicht gleichzeitig leer sein.

  3. preview_text kann nur mit HTML verwendet werden. Ohne HTML-Wert hat preview_text keine Wirkung.

  4. Für Variablenersatz im Inhalt nutzen Sie das Feld vars im JSON-Format, z. B. {"name": ["Mike"], "sp": ["EngageLab"]}. Ist der Wert leer oder ein Leerzeichen, wird der entsprechende Text im E-Mail-Inhalt leer dargestellt.

    Beispiel:
    Nachrichteninhalt: Sehr geehrte:r %name%, willkommen beim %sp%-E-Mail-Service.
    Übergebener vars-Wert: {"name": ["Mike"], "sp": ["EngageLab"]}
    Ergebnis: Sehr geehrter Mike, willkommen beim EngageLab E-Mail-Service.

  5. dynamic_vars dient zum Variablenersatz in dynamischen Templates. Format: JSON-Array, z. B. [{"name":"Jim","sp":"EngageLab"}].

    Beispiel:
    E-Mail-Inhalt: Sehr geehrte:r {{name}}, willkommen bei {{sp}} E-Mail-Service.
    Übergebener Wert in dynamic_vars: [{"name":"Jim","sp":"EngageLab"}]
    Ergebnis: Sehr geehrter Jim, willkommen bei EngageLab E-Mail-Service.

  6. label_id oder label_name kann für diesen Versand übergeben werden. Existiert label_name nicht, wird es automatisch erstellt. Bei gleichzeitiger Angabe hat label_id Vorrang.

  7. headers dient zur Anpassung der E-Mail-Header als JSON-Objekt, z. B. {"User-Define": "123", "User-Custom": "abc"}. Die Schlüssel dürfen folgende Werte nicht enthalten (Groß-/Kleinschreibung egal):
    DKIM-Signature, Received, Sender, Date, From, To, Reply-To, Cc, Bcc, Subject, Content-Type, Content-Transfer-Encoding, X-SENDCLOUD-UUID, X-SENDCLOUD-LOG, X-Remote-Web-IP, X-SMTPAPI, Return-Path, X-SENDCLOUD-LOG-NEW

  8. Bei disposition=inline und Bilddatei wird der Anhang direkt als Inline-Bild im E-Mail-Body angezeigt. content_id muss gesetzt und eindeutig sein und dient als src im HTML.

    Beispiel:
    E-Mail-Inhalt:

    <html> <img src="cid:image_1000"></img> <img src="cid:image_1001"></img> </html>
                  
              <html>
    <img src="cid:image_1000"></img>
    <img src="cid:image_1001"></img>
</html>
    Diesen Codeblock im schwebenden Fenster anzeigen

    attachments-Parameter:

    [ {"content":"Base64-Bildinhalt", "filename": "a23456.jpg","disposition": "inline","content_id": "image_1000"}, {"content":"Base64-Bildinhalt", "filename": "a23457.jpg","disposition": "inline","content_id": "image_1001"} ]
                  
              [
  {"content":"Base64-Bildinhalt", "filename": "a23456.jpg","disposition": "inline","content_id": "image_1000"},
  {"content":"Base64-Bildinhalt", "filename": "a23457.jpg","disposition": "inline","content_id": "image_1001"}
]
    Diesen Codeblock im schwebenden Fenster anzeigen

  9. custom_args werden im Header eingebettet und mit WebHook-Daten zurückgegeben. Die Schlüssel (Keys) dürfen keinen Punkt („.“) enthalten.

  10. request_id verhindert Mehrfachübertragungen, ist eine Stunde lang gültig. Bei Wiederholung innerhalb einer Stunde wird das letzte Ergebnis zurückgegeben.

  11. Die E-Mail darf insgesamt maximal 70 MB groß sein.

Beispiel für eine Anfrage

curl -X POST -H 'Content-Type: application/json; charset=utf-8' \ -H 'Authorization: Basic YXBpX3VzZXI6YXBpX2tleQ==' \ --data '{ "from": "EngageLab Newsletter <newsletter@mail.engagelab.com>", "to": ["111@qq.com", "222<222@qq.com>"], "body": { "cc": ["noreply@mail.engagelab.com"], "bcc": ["intern<intern@mail.engagelab.com>"], "reply_to": ["reply@mail.engagelab.com"], "subject": "%date% Newsletter ", "content": { "html": "<a href=\"https://www.engagelab.com\">Newsletter %kkk%</a>", "text": "Die heutigen Nachrichten: %ttt%", "preview_text": "Vorschau-Text ..." }, "vars": { }, "label_id": 100233, "label_name": "", "headers": {}, "attachments": [{ "content": "Base64-codierter Anhang", "type": "text/html", "filename": "Dateiname des Anhangs", "disposition": "inline | attachment", "content_id": "" }], "settings": { "send_mode": 0, "return_email_id": true, "sandbox": true, "notification": false, "open_tracking": true, "click_tracking": false, "unsubscribe_tracking": true, "unsubscribe_page_id": [1,2] } }, "custom_args": {}, "request_id": "" }' 'https://email.api.engagelab.cc/v1/mail/send' 
              
              curl -X POST -H 'Content-Type: application/json; charset=utf-8' \
     -H 'Authorization: Basic YXBpX3VzZXI6YXBpX2tleQ==' \
     --data '{
  "from": "EngageLab Newsletter <newsletter@mail.engagelab.com>", 
  "to": ["111@qq.com", "222<222@qq.com>"],
  "body": {
      "cc": ["noreply@mail.engagelab.com"],                            
      "bcc": ["intern<intern@mail.engagelab.com>"],                  
      "reply_to": ["reply@mail.engagelab.com"],                         
      "subject": "%date% Newsletter ",                                       
      "content": {                                                     
        "html": "<a href=\"https://www.engagelab.com\">Newsletter %kkk%</a>", 
        "text": "Die heutigen Nachrichten: %ttt%",                                      
        "preview_text": "Vorschau-Text ..."                          
         },
      "vars": { },
      "label_id": 100233, 
      "label_name": "",
      "headers": {},
      "attachments": [{                                                
        "content": "Base64-codierter Anhang",     
        "type": "text/html",
        "filename": "Dateiname des Anhangs",            
        "disposition": "inline | attachment",                           
        "content_id": ""  
      }],
      "settings": {                 
        "send_mode": 0, 
        "return_email_id": true,  
        "sandbox": true,
        "notification": false,
        "open_tracking": true,                                           
        "click_tracking": false,                                         
        "unsubscribe_tracking": true,                              
        "unsubscribe_page_id": [1,2]
      }
  },
  "custom_args": {},           
  "request_id": "" 
}'  'https://email.api.engagelab.cc/v1/mail/send'
Diesen Codeblock im schwebenden Fenster anzeigen

Beispiel für Rückgabewerte

Erfolgsmeldung

HTTP Status: 200

{ "email_ids":[ "1447054895514_15555555_32350_1350.sc-10_10_126_221-inbound0$111@qq.com", "1447054895514_15555555_32350_1350.sc-10_10_126_221-inbound1$222@qq.com" ], "request_id":"" }
              
              {
  "email_ids":[
    "1447054895514_15555555_32350_1350.sc-10_10_126_221-inbound0$111@qq.com",
    "1447054895514_15555555_32350_1350.sc-10_10_126_221-inbound1$222@qq.com"
  ],
  "request_id":""
}
Diesen Codeblock im schwebenden Fenster anzeigen

Fehlermeldung

HTTP Status: 400

{ "code": 30801, "message": "From darf nicht leer sein" }
              
              {
  "code": 30801,
  "message": "From darf nicht leer sein"
}
Diesen Codeblock im schwebenden Fenster anzeigen

Versand per Template

URL

https://email.api.engagelab.cc/v1/mail/sendtemplate
              
              https://email.api.engagelab.cc/v1/mail/sendtemplate
Diesen Codeblock im schwebenden Fenster anzeigen

Content-Type:
Content-Type: application/json; charset=utf-8

HTTP-Request-Methode:
POST

Request Header

Header Typ Erforderlich Beschreibung
Authorization String ja Basic base64(api_user:api_key)

Request Parameter

Parameter Typ Erforderlich Beschreibung
from string ja Absender. Beispiel: support@mail.engagelab.com oder EngageLab Team<support@mail.engagelab.com>. Soll der Produkt- oder Markenname angezeigt werden, nutzen Sie EngageLab Team<support@mail.engagelab.com>. „EngageLab Team“ ist der Absendername, <support@mail.engagelab.com> die Absenderadresse.
to array[string] ja Empfänger:innen. Bis zu 100 Adressen werden unterstützt. Beispiel: ["xjm@hotmail.com","xjm2@gmail.com"]
body object ja E-Mail-Einstellungen
custom_args object nein Optionale, vom Kunden definierte Felder (maximal 1 KB). Die Schlüssel (Keys) dürfen keinen Punkt („.“) enthalten.
request_id string nein ID dieser Versandanfrage; maximal 128 Zeichen. Ist eine Stunde lang gültig.

Body

Parameter Typ Erforderlich Beschreibung
cc array[string] nein CC. Maximal 100 Adressen. Nur bei send_mode=1 gültig.
bcc array[string] nein BCC. Maximal 100 Adressen. Nur bei send_mode=1 gültig.
reply_to array[string] nein Antwortadresse(n). Bis zu 3 Adressen; ohne Angabe wird „from“ verwendet.
subject string nein Betreff. Maximal 256 Zeichen; unterstützt Variablen und Emojis.
template_invoke_name string ja Name des zu verwendenden Templates
vars object nein Variablen für den Inhalt. Bis zu 1 MB; gültig bei send_mode=0 oder 1.
dynamic_vars array[object] nein Dynamische Template-Variablen (maximal 1 MB); gültig bei send_mode=0 oder 1.
label_id string nein Label-ID für diesen Versand
label_name string nein Label-Name für diesen Versand
headers object nein Header (maximal 1 KB). Siehe Hinweise für erlaubte Schlüssel.
attachments array[object] nein Anhänge. Gesamtgröße maximal 10 MB.
content (Anhang) string ja Inhalt des Anhangs (Base64-codiert)
filename string ja Dateiname des Anhangs, z. B. news.pdf
disposition string ja „attachment“ oder „inline“
content_id string nein Bei disposition=inline und Bilddatei erforderlich
settings object nein Sende-Einstellungen
send_mode int nein Versandmodus: 0 = einzeln; 1 = Broadcast (alle Empfänger:innen sichtbar); 2 = Versand an Adressliste. Standard: 0
return_email_id boolean nein Rückgabe der E-Mail-ID, Standard: true
sandbox boolean nein Sandbox-Modus (nur Parameterprüfung, kein Versand). Standard: false
notification boolean nein Lesebestätigung aktivieren, Standard: false. Empfangsroute erforderlich.
open_tracking boolean nein Öffnungstracking aktivieren, Standard-Systemwert. Gültig bei send_mode=0 oder 1.
click_tracking boolean nein Klicktracking aktivieren, Standard-Systemwert. Gültig bei send_mode=0 oder 1.
unsubscribe_tracking boolean nein Abmeldelink aktivieren, Standard-Systemwert. Gültig bei send_mode=0 oder 1.
unsubscribe_page_id array[int] nein Benutzerdefinierte Abmeldeseite(n), Standard-Systemwert. Gültig bei send_mode=0 oder 1.

Hinweise

  1. Bei send_mode=2 ist der Wert von „to“ ein Adresslisten-Kürzel (maximal 5 Einträge). Die Parameter cc und bcc sind in diesem Fall ungültig.

  2. Für Variablenersatz im Inhalt nutzen Sie das Feld vars im JSON-Format, z. B. {"name": ["Mike"], "sp": ["EngageLab"]}. Ist der Wert leer oder ein Leerzeichen, wird der entsprechende Text im E-Mail-Inhalt leer dargestellt.

    Beispiel:
    Nachrichteninhalt: Sehr geehrte:r %name%, willkommen beim %sp%-E-Mail-Service.
    Übergebener vars-Wert: {"name": ["Mike"], "sp": ["EngageLab"]}
    Ergebnis: Sehr geehrter Mike, willkommen beim EngageLab E-Mail-Service.

  3. dynamic_vars dient zum Variablenersatz in dynamischen Templates. Format: JSON-Array, z. B. [{"name":"Jim","sp":"EngageLab"}].

    Beispiel:
    E-Mail-Inhalt: Sehr geehrte:r {{name}}, willkommen bei {{sp}} E-Mail-Service.
    Übergebener Wert in dynamic_vars: [{"name":"Jim","sp":"EngageLab"}]
    Ergebnis: Sehr geehrter Jim, willkommen bei EngageLab E-Mail-Service.

  4. label_id oder label_name kann für diesen Versand übergeben werden. Existiert label_name nicht, wird es automatisch erstellt. Bei gleichzeitiger Angabe hat label_id Vorrang.

  5. headers dient zur Anpassung der E-Mail-Header als JSON-Objekt, z. B. {"User-Define": "123", "User-Custom": "abc"}. Die Schlüssel dürfen folgende Werte nicht enthalten (Groß-/Kleinschreibung egal):
    DKIM-Signature, Received, Sender, Date, From, To, Reply-To, Cc, Bcc, Subject, Content-Type, Content-Transfer-Encoding, X-SENDCLOUD-UUID, X-SENDCLOUD-LOG, X-Remote-Web-IP, X-SMTPAPI, Return-Path, X-SENDCLOUD-LOG-NEW

  6. Bei disposition=inline und Bilddatei wird der Anhang direkt als Inline-Bild im E-Mail-Body angezeigt. content_id muss gesetzt und eindeutig sein und dient als src im HTML.

  7. custom_args werden im Header eingebettet und mit WebHook-Daten zurückgegeben. Die Schlüssel (Keys) dürfen keinen Punkt („.“) enthalten.

  8. request_id verhindert Mehrfachübertragungen, ist eine Stunde lang gültig. Bei Wiederholung innerhalb einer Stunde wird das letzte Ergebnis zurückgegeben.

  9. Die E-Mail darf insgesamt maximal 70 MB groß sein.

Beispiel für Rückgabewerte

Template-Inhalt (month_bill):

Sehr geehrte:r %name%: Hallo! Ihr Verbrauch in diesem Monat beträgt: %money% .
              
              Sehr geehrte:r %name%:
  Hallo! Ihr Verbrauch in diesem Monat beträgt: %money% .
Diesen Codeblock im schwebenden Fenster anzeigen

Standardversand (Template „month_bill“ aufrufen):

curl -X POST "https://email.api.engagelab.cc/v1/mail/sendtemplate" \ --header "Authorization: Basic <<IHR_API_KEY_HIER>>" \ --header "Content-Type: application/json" \ --data '{ "from": "support@mail.engagelab.com", "to": ["xjmfc@126.com", "xjmfcme@gmail.com"], "body": { "subject": "Test-E-Mail", "template_invoke_name": "month_bill", "label_id": 10143, "label_name": "", "vars": { "%name%": ["Jack", "Jonas"], "%money%": ["30", "50"] }, "headers": { "userdefine-tag-location": "us", "userdefine-tag-user": "fashion" }, "attachments": [{ "content": "Base64-codierter Anhang", "filename": "Dateiname des Anhangs", "disposition": "inline | attachment", "content_id": "" }], "settings": { "send_mode": 0, "return_email_id": true, "sandbox": true, "notification": false, "open_tracking": true, "click_tracking": false, "unsubscribe_tracking": true, "unsubscribe_page_id": [1, 2] } }, "custom_args": {}, "request_id": "" }'
              
              curl -X POST "https://email.api.engagelab.cc/v1/mail/sendtemplate" \
--header "Authorization: Basic <<IHR_API_KEY_HIER>>" \
--header "Content-Type: application/json" \
--data '{
    "from": "support@mail.engagelab.com",
    "to": ["xjmfc@126.com", "xjmfcme@gmail.com"],
    "body": {
        "subject": "Test-E-Mail",
        "template_invoke_name": "month_bill",
        "label_id": 10143,
        "label_name": "",
        "vars": {
            "%name%": ["Jack", "Jonas"],
            "%money%": ["30", "50"]
        },
        "headers": {
            "userdefine-tag-location": "us",
            "userdefine-tag-user": "fashion"
        },
        "attachments": [{
            "content": "Base64-codierter Anhang",
            "filename": "Dateiname des Anhangs",
            "disposition": "inline | attachment",
            "content_id": ""
        }],
        "settings": {
            "send_mode": 0,
            "return_email_id": true,
            "sandbox": true,
            "notification": false,
            "open_tracking": true,
            "click_tracking": false,
            "unsubscribe_tracking": true,
            "unsubscribe_page_id": [1, 2]
        }
    },
    "custom_args": {},
    "request_id": ""
}'
Diesen Codeblock im schwebenden Fenster anzeigen

Erhaltene E-Mail:

  • Für xjmfc@126.com:
    Sehr geehrte:r Jack:
    Hallo! Ihr Verbrauch in diesem Monat beträgt: 30.

  • Für xjmfcme@gmail.com:
    Sehr geehrte:r Jonas:
    Hallo! Ihr Verbrauch in diesem Monat beträgt: 50.

Erfolgsmeldung

HTTP Status: 200

{ "email_ids":[ "1447054895514_15555555_32350_1350.sc-10_10_126_221-inbound0$xjmfc@126.com", "1447054895514_15555555_32350_1350.sc-10_10_126_221-inbound1$xjmfcme@gmail.com" ], "request_id":"" }
              
              {
  "email_ids":[
    "1447054895514_15555555_32350_1350.sc-10_10_126_221-inbound0$xjmfc@126.com",
    "1447054895514_15555555_32350_1350.sc-10_10_126_221-inbound1$xjmfcme@gmail.com"
  ],
  "request_id":""
}
Diesen Codeblock im schwebenden Fenster anzeigen

Fehlermeldung

HTTP Status: 404

not found
              
              not found
Diesen Codeblock im schwebenden Fenster anzeigen

Versand von Meeting-Kalendern

URL

https://email.api.engagelab.cc/v1/mail/sendcalendar
              
              https://email.api.engagelab.cc/v1/mail/sendcalendar
Diesen Codeblock im schwebenden Fenster anzeigen

Content-Type:
Content-Type: application/json; charset=utf-8

HTTP-Request-Methode:
POST

Request Header

Header Typ Erforderlich Beschreibung
Authorization String ja Basic base64(api_user:api_key)

Request Parameter

Parameter Typ Erforderlich Beschreibung
from string ja Absender. Beispiel: support@mail.engagelab.com oder EngageLab Team<support@mail.engagelab.com>. Soll der Produkt- oder Markenname angezeigt werden, nutzen Sie EngageLab Team<support@mail.engagelab.com>. „EngageLab Team“ ist der Absendername, <support@mail.engagelab.com> die Absenderadresse.
to array[string] ja Empfänger:innen. Bis zu 100 Adressen werden unterstützt. Beispiel: ["xjm@hotmail.com","xjm2@gmail.com"]
body object ja E-Mail-Einstellungen
custom_args object nein Optionale, vom Kunden definierte Felder (maximal 1 KB). Die Schlüssel (Keys) dürfen keinen Punkt („.“) enthalten.
request_id string nein ID dieser Versandanfrage; maximal 128 Zeichen. Ist eine Stunde lang gültig.

Body

Parameter Typ Erforderlich Beschreibung
cc array[string] nein CC. Maximal 100 Adressen. Nur bei send_mode=1 gültig.
bcc array[string] nein BCC. Maximal 100 Adressen. Nur bei send_mode=1 gültig.
reply_to array[string] nein Antwortadresse(n). Bis zu 3 Adressen; ohne Angabe wird „from“ verwendet.
subject string ja Betreff. Maximal 256 Zeichen; unterstützt Variablen und Emojis.
content object ja Inhalt der E-Mail
html string * HTML-Inhalt. Format: text/html.
text string * Text-Inhalt. Format: text/plain.
preview_text string nein Vorschau-Text. Nur in Verbindung mit HTML wirksam.
vars object nein Variablen für den Inhalt. Bis zu 1 MB; gültig bei send_mode=0 oder 1.
dynamic_vars array[object] nein Dynamische Template-Variablen (maximal 1 MB); gültig bei send_mode=0 oder 1.
label_id string nein Label-ID für diesen Versand
label_name string nein Label-Name für diesen Versand
headers object nein Header (maximal 1 KB). Siehe Hinweise für erlaubte Schlüssel.
attachments array[object] nein Anhänge. Gesamtgröße maximal 10 MB.
content (Anhang) string ja Inhalt des Anhangs (Base64-codiert)
filename string ja Dateiname des Anhangs, z. B. news.pdf
disposition string ja „attachment“ oder „inline“
content_id string ja Bei disposition=inline und Bilddatei erforderlich
settings object nein Sende-Einstellungen
send_mode int nein Versandmodus: 0 = einzeln; 1 = Broadcast (alle Empfänger:innen sichtbar). Standard: 0
return_email_id boolean nein Rückgabe der E-Mail-ID, Standard: true
sandbox boolean nein Sandbox-Modus (nur Parameterprüfung, kein Versand). Standard: false
notification boolean nein Lesebestätigung aktivieren, Standard: false. Empfangsroute erforderlich.
open_tracking boolean nein Öffnungstracking aktivieren, Standard-Systemwert. Nur bei send_mode=0 gültig.
click_tracking boolean nein Klicktracking aktivieren, Standard-Systemwert. Nur bei send_mode=0 gültig.
unsubscribe_tracking boolean nein Abmeldelink aktivieren, Standard-Systemwert. Nur bei send_mode=0 gültig.
unsubscribe_page_id array[int] nein Benutzerdefinierte Abmeldeseite(n), Standard-Systemwert. Nur bei send_mode=0 gültig.
calendar object ja Kalender-Einstellungen
time_zone_id string ja Zeitzonen-ID, z. B. „Europe/Berlin“.
start_time string ja Startzeit des Meetings. Format: yyyy-MM-dd HH:mm:ss
end_time string ja Endzeit des Meetings. Format: yyyy-MM-dd HH:mm:ss
title string ja Titel des Meetings. Maximal 256 Zeichen.
organizer object ja Organisator:in
name (Organisator:in) string nein Name des Organisators/der Organisatorin (maximal 64 Zeichen)
email (Organisator:in) string ja E-Mail des Organisators/der Organisatorin
location string ja Veranstaltungsort. Maximal 128 Zeichen.
description string nein Beschreibung des Meetings. Maximal 1.024 Zeichen.
participators array[object] nein Teilnehmende
name (Teilnehmende) string nein Name der Teilnehmenden (maximal 64 Zeichen)
email (Teilnehmende) string ja E-Mail der Teilnehmenden
alarm_min_before integer nein Erinnerung vor dem Meeting in Minuten (1–60)
action object nein Kalenderaktion
name (Aktion) string nein Aktionsname: create, update, cancel. Standard: create
uid string nein Bei update/cancel erforderlich. UID wird beim Erstellen zurückgegeben.

Hinweise

  1. HTML und Text dürfen nicht gleichzeitig leer sein.

  2. preview_text kann nur mit HTML verwendet werden. Ohne HTML-Wert hat preview_text keine Wirkung.

  3. Für Variablenersatz im Inhalt nutzen Sie das Feld vars im JSON-Format, z. B. {"name": ["Mike"], "sp": ["EngageLab"]}. Ist der Wert leer oder ein Leerzeichen, wird der entsprechende Text im E-Mail-Inhalt leer dargestellt.

    Beispiel:
    Nachrichteninhalt: Sehr geehrte:r %name%, willkommen beim %sp%-E-Mail-Service.
    Übergebener vars-Wert: {"name": ["Mike"], "sp": ["EngageLab"]}
    Ergebnis: Sehr geehrter Mike, willkommen beim EngageLab E-Mail-Service.

  4. dynamic_vars dient zum Variablenersatz in dynamischen Templates. Format: JSON-Array, z. B. [{"name":"Jim","sp":"EngageLab"}].

    Beispiel:
    E-Mail-Inhalt: Sehr geehrte:r {{name}}, willkommen bei {{sp}} E-Mail-Service.
    Übergebener Wert in dynamic_vars: [{"name":"Jim","sp":"EngageLab"}]
    Ergebnis: Sehr geehrter Jim, willkommen bei EngageLab E-Mail-Service.

  5. label_id oder label_name kann für diesen Versand übergeben werden. Existiert label_name nicht, wird es automatisch erstellt. Bei gleichzeitiger Angabe hat label_id Vorrang.

  6. headers dient zur Anpassung der E-Mail-Header als JSON-Objekt, z. B. {"User-Define": "123", "User-Custom": "abc"}. Die Schlüssel dürfen folgende Werte nicht enthalten (Groß-/Kleinschreibung egal):
    DKIM-Signature, Received, Sender, Date, From, To, Reply-To, Cc, Bcc, Subject, Content-Type, Content-Transfer-Encoding, X-SENDCLOUD-UUID, X-SENDCLOUD-LOG, X-Remote-Web-IP, X-SMTPAPI, Return-Path, X-SENDCLOUD-LOG-NEW

  7. Bei disposition=inline und Bilddatei wird der Anhang direkt als Inline-Bild im E-Mail-Body angezeigt. content_id muss gesetzt und eindeutig sein und dient als src im HTML.

  8. custom_args werden im Header eingebettet und mit WebHook-Daten zurückgegeben. Die Schlüssel (Keys) dürfen keinen Punkt („.“) enthalten.

  9. request_id verhindert Mehrfachübertragungen, ist eine Stunde lang gültig. Bei Wiederholung innerhalb einer Stunde wird das letzte Ergebnis zurückgegeben.

  10. Die E-Mail darf insgesamt maximal 70 MB groß sein.

Beispiel für eine Anfrage

curl -X POST 'https://email.api.engagelab.cc/v1/mail/sendcalendar' \ --header 'Authorization: Basic MTIyNF94am06MTJkOGIwODVlNjZhZGUyMmNlNGIwOWI5NjQ2YWQ1ODE=' \ --header 'Content-Type: application/json' \ --data '{ "from": "EngageLab Newsletter <newsletter@mail.engagelab.com>", "to": ["111@qq.com", "222<222@qq.com>"], "body": { "cc": ["noreply@mail.engagelab.com"], "bcc": ["intern<intern@mail.engagelab.com>"], "reply_to": ["reply@mail.engagelab.com"], "subject": "%date% Newsletter ", "content": { "html": "<a href=\"https://www.engagelab.com\">Newsletter %kkk%</a>", "text": "Newsletter %ttt%", "preview_text": "Vorschau-Text ..." }, "label_id": "1233", "label_name": "", "headers": { "userdefine-tag-location": "us", "userdefine-tag-user": "fashion" }, "settings": { "send_mode": 0, "return_email_id": true, "sandbox": true, "notification": false, "open_tracking": true, "click_tracking": false, "unsubscribe_tracking": true, "unsubscribe_page_id": [1,2] }, "calendar": { "time_zone_id":"Europe/Berlin", "start_time": "2025-12-10 10:00:00", "end_time": "2025-12-10 12:00:00", "title": "Projektmeeting", "organizer": { "name": "David", "email": "david@mail.engagelab.com" }, "location": "Konferenzraum 208", "description": "Projekt-Update und nächste Schritte", "alarm_min_before": 5, "participators": [ { "name": "Petra", "email": "petra@engagelab.org" }, { "email": "max@engagelab.org", "name": "Max"}, { "email": "alex@engagelab.org"} ], "action": { "name": "create", "uid": "329r239h239888" } } }, "custom_args": {}, "request_id": "" }'
              
              curl -X POST 'https://email.api.engagelab.cc/v1/mail/sendcalendar' \
--header 'Authorization: Basic MTIyNF94am06MTJkOGIwODVlNjZhZGUyMmNlNGIwOWI5NjQ2YWQ1ODE=' \
--header 'Content-Type: application/json' \
--data '{
  "from": "EngageLab Newsletter <newsletter@mail.engagelab.com>",       
  "to": ["111@qq.com", "222<222@qq.com>"],    
  "body": {
      "cc": ["noreply@mail.engagelab.com"],       
      "bcc": ["intern<intern@mail.engagelab.com>"],         
      "reply_to": ["reply@mail.engagelab.com"], 
      "subject": "%date% Newsletter ", 
      "content": { 
        "html": "<a href=\"https://www.engagelab.com\">Newsletter %kkk%</a>", 
        "text": "Newsletter %ttt%",   
        "preview_text": "Vorschau-Text ..." 
      },
      "label_id": "1233",  
      "label_name": "",
      "headers": {                   
        "userdefine-tag-location": "us",  
        "userdefine-tag-user": "fashion"
      },
      "settings": {                                                    
        "send_mode": 0,        
        "return_email_id": true,     
        "sandbox": true,        
        "notification": false, 
        "open_tracking": true,                          
        "click_tracking": false,                       
        "unsubscribe_tracking": true,  
        "unsubscribe_page_id": [1,2]
      },
      "calendar": {
        "time_zone_id":"Europe/Berlin",
        "start_time": "2025-12-10 10:00:00",  
        "end_time": "2025-12-10 12:00:00",  
        "title": "Projektmeeting",                                              
        "organizer": {      
          "name": "David",        
          "email": "david@mail.engagelab.com"                    
        },
        "location": "Konferenzraum 208",                                         
        "description": "Projekt-Update und nächste Schritte",                                        
        "alarm_min_before": 5,                                         
        "participators": [  
          { 
            "name": "Petra",                                                
            "email": "petra@engagelab.org"
          },                      
          { "email": "max@engagelab.org", "name": "Max"},
          { "email": "alex@engagelab.org"}
        ],
        "action": {                                                      
          "name": "create",   
          "uid": "329r239h239888"                                    
        }
      }
  },
  "custom_args": {},           
  "request_id": "" 
}'
Diesen Codeblock im schwebenden Fenster anzeigen

Erfolgsmeldung

HTTP Status: 200

{ "uid": "20230103T065922Z-uidGen@PC201503200437", "email_ids": [ "1672729159224_15_2942_8497.sc-10_2_226_96-test0$111@qq.com", "1672729159224_15_2942_8497.sc-10_2_226_96-test1$222@qq.com" ], "request_id": "" }
              
              {
    "uid": "20230103T065922Z-uidGen@PC201503200437",
    "email_ids": [
        "1672729159224_15_2942_8497.sc-10_2_226_96-test0$111@qq.com",
        "1672729159224_15_2942_8497.sc-10_2_226_96-test1$222@qq.com"
    ],
    "request_id": ""
}
Diesen Codeblock im schwebenden Fenster anzeigen

Fehlermeldung

HTTP Status: 400

{ "code": 30801, "message": "From darf nicht leer sein" }
              
              {
    "code": 30801,
    "message": "From darf nicht leer sein"
}
Diesen Codeblock im schwebenden Fenster anzeigen

MIME-Versand

URL

https://email.api.engagelab.cc/v1/mail/send_mime
              
              https://email.api.engagelab.cc/v1/mail/send_mime
Diesen Codeblock im schwebenden Fenster anzeigen

Content-Type:
Content-Type: application/json;charset=utf-8

HTTP-Request-Methode:
POST

Request Header

Header Typ Erforderlich Beschreibung
Authorization String ja Basic base64(api_user:api_key)

Request Parameter

Parameter Typ Erforderlich Beschreibung
from string nein Absender. Beispiel: support@mail.engagelab.com oder EngageLab Team<support@mail.engagelab.com>. Soll der Produkt- oder Markenname angezeigt werden, nutzen Sie EngageLab Team<support@mail.engagelab.com>. „EngageLab Team“ ist der Absendername, <support@mail.engagelab.com> die Absenderadresse.
to array[string] nein Empfänger:innen. Bis zu 100 Adressen werden unterstützt. Beispiel: ["xjm@hotmail.com","xjm2@gmail.com"]
body object ja E-Mail-Einstellungen
custom_args object nein Optionale, vom Kunden definierte Felder (maximal 1 KB). Die Schlüssel (Keys) dürfen keinen Punkt („.“) enthalten.
request_id string nein ID dieser Versandanfrage; maximal 128 Zeichen. Ist eine Stunde lang gültig.

Body

Parameter Typ Erforderlich Beschreibung
cc array[string] nein CC-Adressen. Maximal 100 Adressen. Nur bei send_mode=1 gültig.
bcc array[string] nein BCC-Adressen. Maximal 100 Adressen. Nur bei send_mode=1 gültig.
reply_to array[string] nein Antwortadresse(n). Bis zu 3 Adressen; ohne Angabe wird „from“ verwendet.
subject string nein Betreff. Maximal 256 Zeichen; unterstützt Variablen und Emojis.
content object ja E-Mail-Inhalt
raw_message string ja E-Mail-Inhalt im MIME-Format.
vars object nein Variablen für den Inhalt. Bis zu 1 MB; gültig bei send_mode=0 oder 1.
label_id string nein Label-ID für diesen Versand
label_name string nein Label-Name für diesen Versand
headers object nein E-Mail-Header (maximal 1 KB). Siehe Hinweise für erlaubte Schlüssel.
settings object nein Sende-Einstellungen
send_mode int nein Versandmodus: 0 = einzeln; 1 = Broadcast (alle Empfänger:innen sichtbar); Wert von „to“ ist Adresslisten-Adresse. Standard: 0
return_email_id boolean nein Rückgabe der E-Mail-ID, Standard: true
sandbox boolean nein Sandbox-Modus (nur Parameterprüfung, kein Versand). Standard: false
notification boolean nein Lesebestätigung aktivieren, Standard: false. Empfangsroute erforderlich.
open_tracking boolean nein Öffnungstracking aktivieren, Standard-Systemwert. Gültig bei send_mode=0 oder 1.
click_tracking boolean nein Klicktracking aktivieren, Standard-Systemwert. Gültig bei send_mode=0 oder 1.
unsubscribe_tracking boolean nein Abmeldelink aktivieren, Standard-Systemwert. Gültig bei send_mode=0 oder 1.
unsubscribe_page_id array[int] nein Benutzerdefinierte Abmeldeseite(n), Standard-Systemwert. Gültig bei send_mode=0 oder 1.

Hinweise

  1. vars werden für den Variablenersatz im E-Mail-Inhalt verwendet, Format: JSON-Objekt: {"varname":["Wert1","Wert2"]}, wobei varname die Variable im E-Mail-Inhalt ist.

  2. Es ist nur entweder label_id oder label_name wirksam. Bei gleichzeitiger Angabe hat label_id Vorrang. Existiert label_name nicht, wird es automatisch erstellt.

    Beispiel:
    E-Mail-Inhalt: Sehr geehrte:r %name%, willkommen beim %sp%-E-Mail-Service.
    Übergebener vars-Wert: {"name":["Mike"], "sp":["EngageLab"]}
    Ergebnis: Sehr geehrter Mike, willkommen beim EngageLab E-Mail-Service.

  3. headers dienen zur Anpassung der E-Mail-Header als JSON-Objekt: {"User-Define":"123", "User-Custom":"abc"}. Die Schlüssel dürfen folgende Werte nicht enthalten (Groß-/Kleinschreibung egal):
    DKIM-Signature, Received, Sender, Date, From, To, Reply-To, Cc, Bcc, Subject, Content-Type, Content-Transfer-Encoding, X-SENDCLOUD-UUID, X-SENDCLOUD-LOG, X-Remote-Web-IP, X-SMTPAPI, Return-Path, X-SENDCLOUD-LOG-NEW

  4. custom_args sind benutzerdefinierte Inhalte, die im E-Mail-Header eingebettet werden und mit WebHook-Daten zurückgegeben werden. Die Schlüssel (Keys) dürfen keinen Punkt („.“) enthalten.

  5. request_id verhindert Mehrfachübertragungen, ist eine Stunde lang gültig. Bei Wiederholung innerhalb einer Stunde wird das letzte Ergebnis zurückgegeben.

  6. Die E-Mail darf insgesamt maximal 70 MB groß sein.

Beispiel für eine Anfrage

curl -X POST -H 'Content-Type: application/json; charset=utf-8' \ -H 'Authorization: Basic YXBpX3VzZXI6YXBpX2tleQ==' \ --data '{ "from": "EngageLab Newsletter <newsletter@mail.engagelab.com>", "to": ["111@qq.com", "222<222@qq.com>"], "body": { "reply_to": ["reply@mail.engagelab.com"], "subject": "%date% Newsletter ", "content": { "raw_message": "Date: Fri, 8 Aug 2025 18:33:00 +0800 (CST)\r\nFrom: TEST <test@trip.com>\r\nReply-To: test_reply@trip.com\r\nTo: fan_tang@trip.com\r\nMessage-ID:....... " }, "vars": { }, "label_id": 100233, "headers": {}, "settings": { "send_mode": 0, "return_email_id": true, "sandbox": false, "notification": false, "open_tracking": true, "click_tracking": false, "unsubscribe_tracking": true, "unsubscribe_page_id": [1,2] } }, "custom_args": {}, "request_id": "" }' 'https://email.api.engagelab.cc/v1/mail/send_mime' 
              
              curl -X POST -H 'Content-Type: application/json; charset=utf-8' \
     -H 'Authorization: Basic YXBpX3VzZXI6YXBpX2tleQ==' \
     --data '{
  "from": "EngageLab Newsletter <newsletter@mail.engagelab.com>", 
  "to": ["111@qq.com", "222<222@qq.com>"],
  "body": {          
      "reply_to": ["reply@mail.engagelab.com"],                         
      "subject": "%date% Newsletter ",                                       
      "content": {                                                     
        "raw_message": "Date: Fri, 8 Aug 2025 18:33:00 +0800 (CST)\r\nFrom: TEST <test@trip.com>\r\nReply-To: test_reply@trip.com\r\nTo: fan_tang@trip.com\r\nMessage-ID:....... "         
         },
      "vars": { },
      "label_id": 100233,
      "headers": {},
      "settings": {                 
        "send_mode": 0, 
        "return_email_id": true,  
        "sandbox": false,
        "notification": false,
        "open_tracking": true,                                           
        "click_tracking": false,                                         
        "unsubscribe_tracking": true,                              
        "unsubscribe_page_id": [1,2]
      }
  },
  "custom_args": {},           
  "request_id": "" 
}'  'https://email.api.engagelab.cc/v1/mail/send_mime'
Diesen Codeblock im schwebenden Fenster anzeigen

Beispiel für Rückgabewerte

Erfolgsmeldung

HTTP Status: 200

{ "email_ids":[ "1447054895514_15555555_32350_1350.sc-10_10_126_221-inbound0$111@qq.com", "1447054895514_15555555_32350_1350.sc-10_10_126_221-inbound1$222@qq.com" ], "request_id":null }
              
              {
  "email_ids":[
    "1447054895514_15555555_32350_1350.sc-10_10_126_221-inbound0$111@qq.com",
    "1447054895514_15555555_32350_1350.sc-10_10_126_221-inbound1$222@qq.com"
  ],
  "request_id":null
}
Diesen Codeblock im schwebenden Fenster anzeigen

Fehlermeldung

HTTP Status: 400

{ "code": 30893, "message": "Die custom_args müssen im JSON-Format vorliegen" }
              
              {
    "code": 30893,
    "message": "Die custom_args müssen im JSON-Format vorliegen"
}
Diesen Codeblock im schwebenden Fenster anzeigen

Sie möchten die EngageLab E-Mail-API testen oder mehr erfahren?
Demo buchen | Dokumentation herunterladen | Jetzt starten

Diese Dokumentation wurde für den deutschen Markt optimiert und entspricht den Anforderungen an professionelle IT- und Business-Anwender:innen.

icon
Vertrieb kontaktieren