Wofür ist die API?
Mit der API meldest Du Kontakte aus Deiner eigenen Software bei einer Marke an – mit denselben Angaben wie im Anmeldeformular: E-Mail-Adresse, Name, Liste, Tags, eigene Felder und der Einwilligungstext. Außerdem fragst Du den Status eines Kontakts ab, meldest ihn ab oder entfernst ihn von einer Liste.
Über die API werden keine Newsletter versendet. Kampagnen und Automationen erstellst und versendest Du wie gewohnt in Mailena.
Anwendungsfälle – von der Buchungsplattform über das CRM bis zur eigenen App – und ein interaktives Beispiel findest Du auf der Seite API-Anbindung.
In welchen Tarifen ist die API enthalten?
In allen Tarifen, ohne Aufpreis. Nicht verfügbar ist sie in der kostenlosen Testphase und in Demo-Marken – dort antwortet die API mit 403 api_unavailable.
Wie lege ich einen API-Schlüssel an?
- Öffne die Marke und dort Markeneinstellungen → API.
- Vergib einen Namen, an dem Du den Schlüssel später erkennst, etwa „Website“ oder „CRM“.
- Kopiere den Schlüssel sofort und hinterlege ihn in Deiner Software. Er wird nur einmal angezeigt (Format
mlk_xxxxxxxx_…), danach siehst Du nur noch den Anfang.
API-Schlüssel anlegen und widerrufen dürfen Inhaber und Admins. Je Marke sind bis zu 10 aktive Schlüssel möglich. Ein Widerruf wirkt sofort.
Wie rufe ich die API auf?
| Angabe | Wert |
|---|---|
| Basis-Adresse | https://app.mailena.io/api/rest/v1 |
| Anmeldung | Header Authorization: Bearer mlk_… |
| Format | Header Content-Type: application/json |
| Grenzen | 60 Anfragen pro Minute und 2.000 pro Stunde je Schlüssel, 120 pro Minute je IP-Adresse |
Wird eine Grenze überschritten, antwortet die API mit 429 und nennt im Header Retry-After, nach wie vielen Sekunden Du es erneut versuchen kannst.
Wie melde ich einen Kontakt an?
Mit POST /contacts. Pflicht sind die E-Mail-Adresse und der Einwilligungstext:
| Feld | Pflicht | Bedeutung |
|---|---|---|
email | ja | E-Mail-Adresse |
consent.text | ja | Genau der Text, dem die Person zugestimmt hat (mindestens 10 Zeichen) |
consent.source | nein | Wo die Anmeldung stattfand, z. B. „Website-Checkout“ |
consent.ip | nein | IP-Adresse der Person bei der Anmeldung – wird nur verschlüsselt gespeichert |
first_name, last_name | nein | Vor- und Nachname |
list | nein | Liste per Name (Groß-/Kleinschreibung egal) oder ID |
tags | nein | Tags per Name oder ID |
fields | nein | Eigene Felder mit ihrem Schlüssel, siehe GET /fields |
Unbekannte Listen, Tags oder Felder lehnt die API mit 422 ab.
curl -X POST https://app.mailena.io/api/rest/v1/contacts \
-H "Authorization: Bearer $MAILENA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"email": "anna@example.com",
"first_name": "Anna",
"last_name": "Berger",
"list": "Newsletter",
"tags": ["Website"],
"fields": { "geburtstag": "1990-05-01" },
"consent": {
"text": "Ja, ich möchte den Newsletter erhalten.",
"source": "Website-Checkout",
"ip": "203.0.113.5"
}
}'Was passiert nach der Anmeldung?
Double-Opt-in ist immer Pflicht, auch über die API. Mailena verschickt die Bestätigungsmail selbst:
| Ausgangslage | Antwort | `status` | Was passiert |
|---|---|---|---|
| Neue oder noch unbestätigte Adresse | 202 | pending_confirmation | Mailena schickt die Bestätigungsmail |
| Zuvor abgemeldeter Kontakt | 202 | pending_confirmation | Neues Double-Opt-in mit Bestätigungsmail |
| Bereits bestätigter Kontakt | 200 | subscribed | Direkt zur Liste und zu den Tags hinzugefügt |
| Gesperrter Kontakt | 202 | blocked | Keine Mail |
| Gelöschter Kontakt (auch im Papierkorb) | 202 | not_possible | Keine Mail |
Jede Antwort enthält zusätzlich unter message eine Erklärung im Klartext.
Liste, Tags und Daten werden erst übernommen, wenn die Person ihre Anmeldung bestätigt hat. Dabei werden nur leere Felder gefüllt, vorhandene Angaben bleiben unverändert. Je Adresse verschickt Mailena höchstens 3 Bestätigungsmails pro Tag.
Die Antwort sieht so aus:
{
"data": {
"email": "anna@example.com",
"status": "pending_confirmation",
"message": "…"
}
}Als Nachweis speichert Mailena den Einwilligungstext, die Quelle und den Zeitpunkt; die IP-Adresse nur verschlüsselt. Mehr dazu unter Double-Opt-in und Einwilligung und Status.
Welche Listen, Felder und Tags gibt es?
GET /lists– Listen der Marke mitid,nameunddescriptionGET /fields– Standardfelder (email,first_name,last_name) und eigene Felder mitkey,label,typeundoptionsGET /tags– Tags mitidundname
curl https://app.mailena.io/api/rest/v1/fields \
-H "Authorization: Bearer $MAILENA_API_KEY"Wie frage ich den Status eines Kontakts ab?
Mit GET /contacts?email=…. Die Antwort enthält den status – subscribed, pending_confirmation, unsubscribed, blocked oder not_subscribed – sowie Listen, Tags und Felder. Ist die Adresse unbekannt, antwortet die API mit 404.
curl "https://app.mailena.io/api/rest/v1/contacts?email=anna@example.com" \
-H "Authorization: Bearer $MAILENA_API_KEY"Wie melde ich einen Kontakt ab oder entferne ihn von einer Liste?
Es gibt zwei Wege – je nachdem, ob die Person gar keine Newsletter der Marke mehr möchte oder nur eine bestimmte Liste verlassen soll:
| Endpunkt | Wirkung |
|---|---|
POST /contacts/unsubscribe mit {"email": "…"} | Meldet den Kontakt vom Newsletter der ganzen Marke ab – wie der Abmeldelink in einer E-Mail. Wieder angemeldet wird er nur über ein neues Double-Opt-in. |
POST /contacts/remove-from-list mit {"email": "…", "list": "…"} | Entfernt den Kontakt nur von dieser Liste. Die Anmeldung und alle anderen Listen bleiben bestehen. |
Beide antworten mit dem aktuellen Stand des Kontakts – status, Listen und Tags. Ist die Adresse unbekannt, antwortet die API mit 404.
curl -X POST https://app.mailena.io/api/rest/v1/contacts/unsubscribe \
-H "Authorization: Bearer $MAILENA_API_KEY" \
-H "Content-Type: application/json" \
-d '{"email": "anna@example.com"}'Welche Fehler können auftreten?
Fehler haben immer dasselbe Format:
{
"error": {
"code": "validation_failed",
"message": "…",
"fields": { "consent.text": ["…"] }
}
}| Antwort | `code` | Bedeutung |
|---|---|---|
401 | invalid_api_key | Schlüssel fehlt, ist falsch oder wurde widerrufen |
403 | api_unavailable | Die Marke ist in der Testphase oder eine Demo-Marke |
404 | – | Kontakt unbekannt (bei der Statusabfrage) |
422 | validation_failed | Angaben fehlen oder passen nicht, z. B. unbekannte Liste – Details unter fields |
429 | – | Zu viele Anfragen – nach Retry-After Sekunden erneut versuchen |
Alle Endpunkte im Überblick
| Methode | Pfad | Zweck |
|---|---|---|
GET | /lists | Listen der Marke |
GET | /fields | Standard- und eigene Felder |
GET | /tags | Tags der Marke |
GET | /contacts?email=… | Status eines Kontakts |
POST | /contacts | Kontakt anmelden bzw. zur Liste hinzufügen |
POST | /contacts/unsubscribe | Vom Newsletter der Marke abmelden |
POST | /contacts/remove-from-list | Von einer Liste entfernen |
Häufige Fragen
Was ist der Unterschied zwischen Abmelden und Entfernen von einer Liste?
/contacts/unsubscribe) beendet die Anmeldung für alle Newsletter der Marke – wie der Abmeldelink. Entfernen (/contacts/remove-from-list) nimmt den Kontakt nur aus einer Liste; er bleibt angemeldet und auf allen anderen Listen.Kann ich über die API Newsletter versenden?
Kostet die API extra?
Kann ich Kontakte ohne Bestätigungsmail hinzufügen?
Brauche ich für WooCommerce die API?
Noch eine Frage offen? Schreib uns an support@mailena.io – wir antworten auf Deutsch. Zuletzt mit der App abgeglichen am 10. November 2026.