Zum Inhalt springen
Kostenlos testen

Integrationen und API

API – Kontakte aus Deiner Software verwalten

Mit der Mailena-API meldest Du Kontakte aus Deiner eigenen Software an, fragst ihren Status ab, meldest sie ab oder entfernst sie aus Listen – etwa aus Deinem Website-Backend, Deinem CRM oder einem Shop ohne Plugin. Rechtlich funktioniert das wie ein Anmeldeformular, inklusive Double-Opt-in.

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?

  1. Öffne die Marke und dort Markeneinstellungen → API.
  2. Vergib einen Namen, an dem Du den Schlüssel später erkennst, etwa „Website“ oder „CRM“.
  3. 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?

Tabelle: Angabe, Wert
AngabeWert
Basis-Adressehttps://app.mailena.io/api/rest/v1
AnmeldungHeader Authorization: Bearer mlk_…
FormatHeader Content-Type: application/json
Grenzen60 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:

Tabelle: Feld, Pflicht, Bedeutung
FeldPflichtBedeutung
emailjaE-Mail-Adresse
consent.textjaGenau der Text, dem die Person zugestimmt hat (mindestens 10 Zeichen)
consent.sourceneinWo die Anmeldung stattfand, z. B. „Website-Checkout“
consent.ipneinIP-Adresse der Person bei der Anmeldung – wird nur verschlüsselt gespeichert
first_name, last_nameneinVor- und Nachname
listneinListe per Name (Groß-/Kleinschreibung egal) oder ID
tagsneinTags per Name oder ID
fieldsneinEigene 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:

Tabelle: Ausgangslage, Antwort, `status`, Was passiert
AusgangslageAntwort`status`Was passiert
Neue oder noch unbestätigte Adresse202pending_confirmationMailena schickt die Bestätigungsmail
Zuvor abgemeldeter Kontakt202pending_confirmationNeues Double-Opt-in mit Bestätigungsmail
Bereits bestätigter Kontakt200subscribedDirekt zur Liste und zu den Tags hinzugefügt
Gesperrter Kontakt202blockedKeine Mail
Gelöschter Kontakt (auch im Papierkorb)202not_possibleKeine 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:

Antwort
{
  "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 mit id, name und description
  • GET /fields – Standardfelder (email, first_name, last_name) und eigene Felder mit key, label, type und options
  • GET /tags – Tags mit id und name
cURL
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
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:

Tabelle: Endpunkt, Wirkung
EndpunktWirkung
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:

Fehler
{
  "error": {
    "code": "validation_failed",
    "message": "…",
    "fields": { "consent.text": ["…"] }
  }
}
Tabelle: Antwort, `code`, Bedeutung
Antwort`code`Bedeutung
401invalid_api_keySchlüssel fehlt, ist falsch oder wurde widerrufen
403api_unavailableDie Marke ist in der Testphase oder eine Demo-Marke
404–Kontakt unbekannt (bei der Statusabfrage)
422validation_failedAngaben 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

Tabelle: Methode, Pfad, Zweck
MethodePfadZweck
GET/listsListen der Marke
GET/fieldsStandard- und eigene Felder
GET/tagsTags der Marke
GET/contacts?email=…Status eines Kontakts
POST/contactsKontakt anmelden bzw. zur Liste hinzufügen
POST/contacts/unsubscribeVom Newsletter der Marke abmelden
POST/contacts/remove-from-listVon einer Liste entfernen

Häufige Fragen

Was ist der Unterschied zwischen Abmelden und Entfernen von einer Liste?

Abmelden (/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?

Nein. Die API ist für Anmeldungen und Kontaktpflege gedacht. Kampagnen und Automationen erstellst und versendest Du in Mailena.

Kostet die API extra?

Nein. Sie ist in allen Tarifen enthalten – nur nicht in der kostenlosen Testphase und in Demo-Marken.

Kann ich Kontakte ohne Bestätigungsmail hinzufügen?

Nein. Neue Adressen bestätigen ihre Anmeldung immer per Double-Opt-in. Bereits bestätigte Kontakte fügt die API direkt zur Liste hinzu.

Brauche ich für WooCommerce die API?

Nein. Für WooCommerce gibt es das Mailena-Plugin. Die API ist für alles andere gedacht – etwa ein eigenes Website-Backend, ein CRM oder einen Shop ohne Plugin.

Noch eine Frage offen? Schreib uns an support@mailena.io – wir antworten auf Deutsch. Zuletzt mit der App abgeglichen am 10. November 2026.