Mailpro™ Email API v2 : Referenz

Die Mailpro™ Email API v2 ermöglicht Ihnen die programmatische Verwaltung von Kontaktlisten, E-Mail-Vorlagen, Absenderadressen und Kampagnen — sowie den Versand von Massen- und Transaktions-E-Mails.

Authentifizierung

Jeder Endpunkt akzeptiert drei Authentifizierungsmethoden. Verwenden Sie diejenige, die zu Ihrem Stack passt.

> Der Legacy-Bearer-JWT und IdClient+ApiKey funktionieren unverändert weiter und unterliegen keiner > Scope-Prüfung. Nur OAuth-2.0-Zugriffstokens unterliegen den Scope-Prüfungen pro Endpunkt, > die bei jeder Operation unten angegeben sind.

Methode 1 — OAuth 2.0 (empfohlen für Integrationen)

Mailpro betreibt einen einzigen OAuth-2.0-Autorisierungsserver für alle seine APIs, unter einer einheitlichen, versionsunabhängigen Adresse: https://api.mailpro.com/oauth/. Es gibt keinen OAuth-Endpunkt pro Version — Sie erhalten ein Token über /oauth/token, und dasselbe Token funktioniert mit dieser Email API v2, mit CRM v3 und mit SMS. Welche Endpunkte es aufrufen darf, bestimmen die Scopes des Tokens, nicht die Basis-URL der API. Aussteller (iss-Claim): https://api.mailpro.com/oauth/.

Endpunkt	URL
Autorisierung	`GET https://api.mailpro.com/oauth/authorize`
Token / Erneuerung	`POST https://api.mailpro.com/oauth/token`
JWKS	`GET https://api.mailpro.com/oauth/.well-known/jwks`
Discovery	`GET https://api.mailpro.com/oauth/.well-known/openid-configuration`

Grants: authorization_code + PKCE (S256, obligatorisch), client_credentials, refresh_token (Rotation). Gültigkeit des Zugriffstokens: 20 Min.; Refresh-Token: 30 Tage (gleitend, einmalig verwendbar); Autorisierungscode: 60 s.

Schnellstart — Token abrufen und diese API aufrufen (Platzhalter ersetzen; committen Sie niemals ein echtes Secret):

Rufen Sie anschließend diese API mit Authorization: Bearer ACCESS_TOKEN auf. Dasselbe Token funktioniert mit den APIs CRM v3 und SMS. Ein Token, dem der für einen Endpunkt erforderliche Scope fehlt, erhält 403 insufficient_scope. Vollständiger Ablauf und Scope-Katalog: siehe die Dokumentation der CRM v3 API › Authentifizierung. Für E-Mail relevante Scopes: email:send, email:read, email:templates:read, email:templates:write, contacts:read, contacts:write, account:read.

Methode 2 — Bearer JWT (Legacy)

Sie erhalten ein Token über POST /token (form-kodiert, OAuth2 Password Grant):

Dasselbe Token ist auch für die CRM API v3 und die SMS API gültig — einmal authentifizieren, jede API aufrufen. Tokens sind standardmäßig 30 Tage lang gültig; verwenden Sie grant_type=refresh_token, um sie ohne erneute Authentifizierung zu erneuern. Ohne Scopes — bevorzugen Sie OAuth 2.0 für installierbare Integrationen.

Methode 3 — IdClient + ApiKey

OAuth-Scope-Prüfung pro Endpunkt (Email v2)

Parameter	Typ	Beschreibung
`IdClient`	integer	Ihre numerische Mailpro-Kundennummer, zu finden unter Einstellungen → API-Zugang
`ApiKey`	string	Ihr API-Schlüssel, zu finden unter Einstellungen → API-Zugang

Für per OAuth ausgestellte Tokens verlangt jede Endpunktgruppe einen Scope (die Legacy-Authentifizierung ist davon ausgenommen). Jede Operation nennt ihren Scope unter Authorization. Übersicht:

Endpunkte	Erforderlicher Scope
`/send/*` (Kampagnen, Transaktional, Planung, Test — außer `/send/{IdSend}/status`)	`email:send`
`/stats/*` (außer `/stats/del`), `/history/list`, `/send/{IdSend}/status`	`email:read`
`/message/`, `/senderEmail/` (Lesen)	`email:templates:read`
`/message/`, `/senderEmail/` (add/edit/del), `/stats/del`	`email:templates:write`
`/list/list`, `/email/list`	`contacts:read`
`/list/{add,edit,del}`, `/email/{add,addSingle,edit,del}`, `/import/upload`	`contacts:write`
`/account/*`	`account:read`

Eine Scope-Ablehnung liefert 403 mit { "error": "insufficient_scope", "required_scope": "…" }.

Antwortformat

Alle Endpunkte unterstützen json (Standard) und xml. Geben Sie das Format in der URL an:

Paginierung

Gleiche Regel für die drei Mailpro-APIs (Email v2, CRM v3, SMS): 5.000 Einträge pro Seite, standardmäßig und maximal.

Unbekannte Parameter werden ignoriert, nie abgelehnt. Enthält eine Anfrage einen Parameter, den die API nicht kennt, enthält die Antwort X-Ignored-Parameters (die Namen) und X-Documentation (einen Link zu dieser Seite), damit ein Tippfehler nicht unbemerkt bleibt.

Fehlerantworten

Zustellverfolgung (transaktionale E-Mails)

HTTP	Bedeutung
400	Bad Request — fehlender oder ungültiger Pflichtparameter
401	Unauthorized — ungültige `IdClient` oder ungültiger `ApiKey`
403	Verboten — Kontolimit erreicht (z. B. maximale Anzahl an Listen)
404	Nicht gefunden — die angeforderte Ressource existiert nicht
500	Interner Serverfehler

Jede einzeln versendete E-Mail (POST /send/sendmail, die CRM API v3, das SMTP-Relay oder eine Automatisierung) erhält eine Kennung. Sie kann verfolgt werden, bis der Server des Empfängers sie annimmt oder ablehnt. Kampagnen sind hier nicht abgedeckt: Nutzen Sie die Statistiken.

Webhooks

Mailpro™ kann Ihren Server in Echtzeit benachrichtigen, wenn bestimmte Ereignisse in Ihrem Konto eintreten (eine E-Mail wird zugestellt, eine Kampagne wird abgeschlossen, ein Kontakt erzeugt einen Bounce usw.). Im Stil von Stripe — Ihre URL empfängt einen HMAC-SHA256-signierten POST, sobald das Ereignis ausgelöst wird.

Jedes an Ihren Webhook gesendete Ereignis zählt als 1 Anfrage in Ihrem Kontingent an API-Anfragen.

Funktionsweise

`status`	Bedeutung	Endgültig?
`queued`	Angenommen, wartet auf den Versand.	nein
`scheduled`	Für später geplant (`DatePlanned`).	nein
`sent`	Von unseren Servern übergeben, noch keine Antwort des Empfängerservers.	nein
`delivered`	Vom Empfängerserver angenommen (`DiagCode` = seine SMTP-Antwort).	ja
`bounced`	Abgelehnt. `BounceType`: `hard` = ungültige Adresse oder endgültige Ablehnung; `soft` = Ablehnung nach erneuten Versuchen (Postfach voll, Server nicht erreichbar …).	ja
`not_found`	Unbekannte Kennung oder Kennung, die nicht zu Ihrem Konto gehört.	ja

> ⏱ Aktivierungsverzögerung — nach dem Erstellen, Aktualisieren oder Löschen eines Webhooks dauert es > bis zu 10 Minuten, bis die Änderung auf allen Mailpro-API-Servern wirksam wird. > In diesem Zeitfenster werden Ereignisse möglicherweise noch nicht von Ihrem neuen Abonnement erfasst > (oder weiterhin von einem soeben entfernten erfasst). Dies ist die Zeit, die erforderlich ist, um > den In-Memory-Abonnement-Cache auf jeder API-Instanz zu aktualisieren.

Payload-Umschlag

Ereigniskatalog

Feld	Format	Beschreibung
`id`	`evt_` + 32 hex	Eindeutige Ereignis-ID — verwenden Sie sie auf Ihrer Seite als Idempotenzschlüssel.
`type`	`<domain>.<verb>`	Kanonischer Ereignistyp.
`created`	Unix-Sekunden UTC	In der HMAC-Signatur enthalten.
`apiVersion`	`"v2"`	Welche Mailpro-API das Ereignis veröffentlicht hat.
`account.id`	int	Ihre Mailpro-Kundennummer (= `IdClient`).
`account.name`	string	Ihr Kontoname (praktisch für clientseitiges Debugging).
`data`	object	Ereignis-Payload — die Struktur hängt vom `type` ab (siehe Katalog unten).

Ereignis	Auslöser	`data`-Struktur
`ping`	Test über `POST /webhooks/{id}/test`	`{ message }`
`email.processed`	Versand von der Pipeline akzeptiert	`{ messageId, email, campaignId, processedAt }`
`email.delivered`	Eine einzelne E-Mail wurde vom Empfängerserver angenommen — API v2/v3, SMTP oder Automation (nicht Kampagnen). Aus dem PowerMTA-Zustellstrom ausgelöst.	`{ messageId, email, idSending, sendingType, diagCode, deliveredAt }`
`email.opened`	Tracking-Pixel-Treffer	`{ messageId, email, campaignId, openedAt, ip, userAgent }`
`email.clicked`	Klick auf einen getrackten Link	`{ messageId, email, campaignId, clickedAt, url, ip, userAgent }`
`email.bounced`	Hard- oder Soft-Bounce	`{ messageId, email, campaignId, bouncedAt, bounceType, reason }`
`email.spam_report`	FBL-Beschwerde	`{ messageId, email, campaignId, reportedAt }`
`email.unsubscribed`	Abmelde-Link angeklickt	`{ messageId, email, campaignId, unsubscribedAt }`
`email.dropped`	Vor dem Versand abgelehnt	`{ messageId, email, campaignId, droppedAt, reason }`
`campaign.started`	Versand beginnt	`{ campaignId, name, totalRecipients, startedAt }`
`campaign.finished`	Alle Empfänger verarbeitet	`{ campaignId, name, totalSent, totalFailed, finishedAt }`
`credits.low`	E-Mail-Credit-Guthaben unter Ihrem Warnschwellenwert	`{ remaining, threshold }`

Abonnieren Sie alle Ereignisse dieser API, indem Sie ["*"] im events-Array übergeben.

HMAC-Signatur

Node.js

PHP

Python

Wiederholungen und automatische Deaktivierung

Versuch	Verzögerung vor dem nächsten Versuch
1 → 2	10 Sekunden
2 → 3	1 Minute
3 → 4	5 Minuten
4 → 5	30 Minuten
5 → 6	2 Stunden
6 → 7	6 Stunden
7	abgebrochen (Zustellung als `failed` markiert)

Nach 10 aufeinanderfolgenden Fehlschlägen auf demselben Webhook wird dieser automatisch deaktiviert (isActive: false) und Sie erhalten eine Benachrichtigungs-E-Mail. Aktivieren Sie ihn mit PUT /webhooks/{id} erneut, sobald Ihr Endpunkt repariert ist.

Erfolg = HTTP 2xx

Wir betrachten Ihren Webhook nur dann als erfolgreich, wenn Sie einen Status im Bereich 200–299 zurückgeben. Jeder 3xx/4xx/5xx oder ein Timeout (> 10 s) zählt als Fehlschlag und löst Wiederholungen aus. Falls Ihr Endpunkt dauerhaft nicht mehr erreichbar ist, geben Sie explizit 410 Gone zurück — Wiederholungen werden weiterhin durchgeführt, aber der Grund des Fehlschlags ist in Ihrem Zustellungsprotokoll klarer ersichtlich.

Limits

Inhalt

Authentication

Limit	Wert
Webhooks pro Konto	20
Abonnierte Ereignisse pro Webhook	50
Maximale Payload-Größe	256 KB
HTTP-Timeout pro Versuch	10 Sekunden
Aufbewahrungsdauer des Zustellungsverlaufs	30 Tage

Beziehen Sie ein Bearer-JWT-Token, um alle anderen API-Aufrufe zu authentifizieren. Der v2-Endpunkt /token ist eine 307-Weiterleitung an den kanonischen Aussteller /v3/token — Ihr HTTP-Client folgt der Weiterleitung transparent (POST-Methode und Body bleiben erhalten).

POST `/token`

Access-Token beziehen (307-Weiterleitung zu /v3/token)

Bezieht ein Bearer-JWT-Token unter Verwendung der Mailpro-Client-Zugangsdaten. Übergeben Sie das zurückgegebene access_token in allen nachfolgenden Anfragen als Authorization: Bearer <token>. Dasselbe Token ist auch für die CRM API v3 und die SMS API gültig.

> ⚙ Implementierungsdetail — POST /v2/token ist eine 307 Temporary > Redirect zu POST /v3/token (konfiguriert auf der IIS-web.config- > Rewrite-Ebene). HTTP 307 erhält sowohl die Methode (POST) als > auch den Request-Body, sodass jeder standardkonforme HTTP-Client > der Weiterleitung transparent folgt — Sie senden weiterhin POST-Anfragen > an /v2/token und erhalten ein gültiges JWT zurück. Es gibt keine > doppelte Token-Ausstellungslogik; die Email v2 API stellt selbst niemals > Tokens aus.

Unterstützte Grant-Typen

Grant-Typ	Anwendungsfall
`password`	Standardintegration — Benutzername + API-Schlüssel
`refresh_token`	Erneuern eines ablaufenden Access-Tokens ohne erneute Authentifizierung
`client_credentials`	Server-zu-Server allein mit Client-Kennung

Token-Lebensdauer

Access-Token: 30 Tage
Refresh-Token: 90 Tage

Verwenden Sie grant_type=refresh_token, um das Access-Token ohne erneute Authentifizierung zu erneuern. Speichern Sie Tokens serverseitig (Vault, Umgebungsvariablen); betten Sie sie niemals in Browser-JS oder Mobile-App- Binärdateien ein. Den vollständigen Sicherheitshinweis finden Sie in der Dokumentation des CRM-API-v3-Endpunkts /token.

Anfragetext (application/x-www-form-urlencoded)

Name	Typ	Erforderlich	Beschreibung
`grant_type`	string: password, refresh_token, client_credentials	ja
`username`	string		Ihr Mailpro-Benutzername (E-Mail). Erforderlich für den `password`-Grant.
`password`	string		Ihr Mailpro-API-Schlüssel (GUID-Format). Erforderlich für den `password`-Grant.
`refresh_token`	string		Vorheriges Refresh-Token. Erforderlich für den `refresh_token`-Grant.
`client_id`	string		Ihre Mailpro-Kundenkennung (Ganzzahl). Erforderlich für den `client_credentials`-Grant.

Antworten

Code	Beschreibung
`200`	Token erfolgreich ausgestellt. Wird von `POST /v3/token` nach dem transparenten 307-Follow zurückgegeben — Ihr HTTP-Client erhält ein normales 200 mit derselben Body-Struktur, die er direkt vom v3-Token- Endpunkt erhalten würde.
`307`	Temporäre Weiterleitung an `POST /v3/token`, ausgestellt durch die IIS-Rewrite-Regel in `web.config`. Standardkonforme HTTP-Clients folgen dieser automatisch und erhalten dabei die ursprüngliche POST-Methode und den Formular-Body. Nur für Clients sichtbar, die das Folgen von Weiterleitungen explizit deaktivieren (z. B. `curl --max-redirs 0`).
`400`	Ungültige Zugangsdaten oder nicht unterstützter Grant-Typ

Beispiel 200

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer",
  "expires_in": 31535999,
  "userName": "12345",
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "application": null
}

Beispiel 400

{
  "error": "invalid_grant",
  "error_description": "The username or password is incorrect."
}

Account

Prüfen Sie Ihr E-Mail-Credit-Guthaben, Ihr monatliches API-Kontingent und Ihren Abonnementstatus.

Code	Beschreibung
`200`	Credit-Guthaben erfolgreich zurückgegeben
`401`	Ungültige Zugangsdaten

Code	Beschreibung
`200`	Ablaufdatum des Abonnements erfolgreich zurückgegeben
`401`	Ungültige Zugangsdaten

GET `/account/limits.{format}`

Monatliches API-Kontingent abrufen

Gibt das monatliche API-Anfrage-Kontingent für den authentifizierten Client zurück.

Kontingentberechnung: Das Limit wird aus den E-Mail-Abonnement-Credits abgeleitet (typischerweise subscription_credits × 5). Bei einem Plan mit 10.000 E-Mails/Monat ergibt das ein monatliches Budget von 50.000 Anfragen. Zurückgesetzt am Jahrestag des Abonnements (nicht am Ersten des Kalendermonats).

Was Credits verbraucht:

Jede authentifizierte API-Anfrage an die Endpunkte v2, v3 oder sms.
Jedes Webhook-Ereignis, das an einen abonnierten Endpunkt zugestellt wird.

Was KOSTENLOS ist (verbraucht keine Credits):

/health-Endpunkte.
Anfragen, die mit 401, 403 oder 429 fehlschlagen.
Webhook-Ereignisse für Clients ohne passendes Abonnement.

Das Kontingent wird über alle 3 Mailpro-APIs (v2, v3, sms) hinweg geteilt — ein Kunde = ein monatliches Budget für die gesamte Plattform.

OAuth-Scope : account:read

Parameter

Name	Ort	Typ	Erforderlich	Beschreibung
`format`	path	string: json, xml	ja	Antwortformat

Antworten

Code	Beschreibung
`200`	Momentaufnahme des Kontingents
`401`	Ungültige Zugangsdaten
`404`	Kein Kontingent-Datensatz gefunden (neu erstelltes Konto; der Eintrag wird bei der ersten authentifizierten Anfrage angelegt).

Beispiel 200

{
  "MonthlyLimit": 50000,
  "Remaining": 32847,
  "Used": 17153,
  "IsFree": false,
  "RemainedSendsForFree": 0
}

Lists

Verwalten Sie Listen (Kontaktlisten). Eine Liste gruppiert Kontakte für Massenkampagnen. Maximal 1.000 Listen pro Konto (gleiche Grenze für die drei Mailpro-APIs und in der App). Type 0 = Standardliste. Type 1 = Sperrliste (zur Verwaltung von Abmeldungen).

GET `/list/list.{format}`

Alle Listen auflisten

Gibt alle Listen des Kontos zurück, sortiert nach Erstellungsdatum (neueste zuerst), sofern nicht sortByName=true gesetzt ist. Verwenden Sie type=0 für reguläre Listen oder type=1 für Sperrlisten.

> Veralteter Alias: /addressbook/list.{format} — derselbe Endpunkt, aus Gründen der Abwärtskompatibilität beibehalten. Neue Integrationen sollten /list/* verwenden.

OAuth-Scope : contacts:read

Parameter

Name	Ort	Typ	Erforderlich	Beschreibung
`format`	path	string: json, xml	ja	Antwortformat
`titleFilter`	query	string		Nach Titel filtern (teilweise, Groß-/Kleinschreibung ignorierend)
`type`	query	integer: 0, 1		`0` = nur Standardlisten, `1` = nur Sperrlisten. Weglassen, um alle zurückzugeben.
`numberOfRecords`	query	integer		Einträge pro Seite — standardmäßig und maximal 5.000 (siehe Paginierung).
`pageNumber`	query	integer		Seitennummer (1-basiert). Standardwert ist 1.
`sortByName`	query	boolean		Auf `true` setzen, um die Ergebnisse alphabetisch nach Titel zu sortieren

Antworten

Code	Beschreibung
`200`	Listen erfolgreich zurückgegeben. > Die Antwort enthält zusätzlich das veraltete Duplikat-Feld `AddressBookList` (identischer Inhalt), und jedes Element enthält ein veraltetes Duplikat `AddressBookID` (identisch mit `ListID`). Neue Integrationen sollten diese ignorieren.
`401`	Ungültige Zugangsdaten

Beispiel 200

{
  "Lists": [
    {
      "ListID": 101,
      "Title": "Newsletter — France",
      "Type": 0,
      "NumberEmails": 4521,
      "CreationDate": "2025-01-15T10:30:00"
    },
    {
      "ListID": 102,
      "Title": "Unsubscribers",
      "Type": 1,
      "NumberEmails": 312,
      "CreationDate": "2025-01-15T10:31:00"
    }
  ]
}

POST `/list/add.{format}`

Liste erstellen

Erstellt eine neue Liste (Kontaktliste). Die Liste ist zunächst leer — fügen Sie Kontakte über /email/add oder /email/addSingle hinzu. Maximal 1.000 Listen pro Konto (gleiche Grenze für die drei Mailpro-APIs und in der App). Gibt HTTP 422 zurück, wenn das Limit erreicht ist.

> Veralteter Alias: /addressbook/add.{format} — derselbe Endpunkt, aus Gründen der Abwärtskompatibilität beibehalten.

OAuth-Scope : contacts:write

Parameter

Name	Ort	Typ	Erforderlich	Beschreibung
`format`	path	string: json, xml	ja	Antwortformat

Anfragetext (application/x-www-form-urlencoded)

Name	Typ	Erforderlich	Beschreibung
`Title`	string	ja	Anzeigename für die neue Liste
`Type`	integer: 0, 1		`0` = Standardliste (Standard), `1` = Sperrliste

Antworten

Code	Beschreibung
`200`	Liste erfolgreich erstellt. > Ein veraltetes Duplikat-Feld `AddressBookList` wird ebenfalls zurückgegeben (identischer Inhalt).
`400`	Fehlender Titel
`401`	Ungültige Zugangsdaten
`422`	Listenlimit (1.000) erreicht

Beispiel 200

{
  "Lists": [
    {
      "ListID": 103,
      "Title": "Spring Campaign 2026",
      "Type": 0,
      "NumberEmails": 0,
      "CreationDate": "2026-04-14T12:00:00"
    }
  ]
}

POST `/list/edit.{format}`

Liste umbenennen

Aktualisiert den Titel einer bestehenden Liste. Die enthaltenen Kontakte sind davon nicht betroffen.

> Veralteter Alias: /addressbook/edit.{format} — derselbe Endpunkt, aus Gründen der Abwärtskompatibilität beibehalten. > Der Parametername AddressBookID wird ebenfalls als veralteter Alias für ListID akzeptiert.

OAuth-Scope : contacts:write

Parameter

Name	Ort	Typ	Erforderlich	Beschreibung
`format`	path	string: json, xml	ja	Antwortformat

Anfragetext (application/x-www-form-urlencoded)

Name	Typ	Erforderlich	Beschreibung
`ListID`	integer	ja	Kennung der umzubenennenden Liste (aus `/list/list`). Der veraltete Alias `AddressBookID` wird ebenfalls akzeptiert.
`Title`	string	ja	Neuer Titel der Liste

Antworten

Code	Beschreibung
`200`	Liste erfolgreich umbenannt
`400`	Fehlende ListID oder fehlender Titel
`401`	Ungültige Zugangsdaten
`404`	Liste nicht gefunden

POST `/list/del.{format}`

Liste löschen

Löscht eine Liste und alle darin enthaltenen Kontakte dauerhaft. Diese Aktion kann nicht rückgängig gemacht werden.

> Veralteter Alias: /addressbook/del.{format} — derselbe Endpunkt, aus Gründen der Abwärtskompatibilität beibehalten. > Der Parametername AddressBookID wird ebenfalls als veralteter Alias für ListID akzeptiert.

OAuth-Scope : contacts:write

Parameter

Name	Ort	Typ	Erforderlich	Beschreibung
`format`	path	string: json, xml	ja	Antwortformat

Anfragetext (application/x-www-form-urlencoded)

Name	Typ	Erforderlich	Beschreibung
`ListID`	integer	ja	Kennung der zu löschenden Liste. Der veraltete Alias `AddressBookID` wird ebenfalls akzeptiert.

Antworten

Code	Beschreibung
`200`	Liste erfolgreich gelöscht
`400`	Fehlende ListID
`401`	Ungültige Zugangsdaten
`404`	Liste nicht gefunden

Beispiel 200

{
  "Result": "OK"
}

Contacts

Verwalten Sie einzelne E-Mail-Kontakte. Kontakte gehören zu einer oder mehreren Listen. Verwenden Sie den Massenimport (/email/add) für große Stapel oder das Hinzufügen einzelner Kontakte (/email/addSingle) für individuelle Anmeldungen mit benutzerdefinierten Feldwerten.

GET `/email/list.{format}`

Kontakte auflisten

Gibt eine paginierte Liste der E-Mail-Kontakte des Kontos zurück. Filtern Sie nach Liste oder nach E-Mail-Muster. Die Ergebnisse sind bei sortByName=true alphabetisch sortiert, andernfalls nach Einfügereihenfolge.

OAuth-Scope : contacts:read

Parameter

Name	Ort	Typ	Erforderlich	Beschreibung
`format`	path	string: json, xml	ja	Antwortformat
`emailFilter`	query	string		Nach E-Mail-Adresse filtern (teilweise, Groß-/Kleinschreibung ignorierend)
`listId`	query	integer		Nur Kontakte in dieser Liste zurückgeben. Der veraltete Alias `addressBookId` wird ebenfalls akzeptiert.
`numberOfRecords`	query	integer		Einträge pro Seite — standardmäßig und maximal 5.000 (siehe Paginierung).
`pageNumber`	query	integer		Seitennummer (1-basiert). Standardwert ist 1.
`sortByName`	query	boolean		Auf `true` setzen, um die Ergebnisse alphabetisch nach E-Mail-Adresse zu sortieren

Antworten

Code	Beschreibung
`200`	Kontaktliste erfolgreich zurückgegeben
`401`	Ungültige Zugangsdaten

Beispiel 200

{
  "Emails": [
    {
      "IdEmail": 10001,
      "Email": "[email protected]",
      "Field1": "Alice",
      "Field2": "Dupont"
    }
  ]
}

POST `/email/add.{format}`

Kontakte importieren (Massenimport)

Importiert eine oder mehrere E-Mail-Adressen in einem einzigen Anfrageaufruf in eine Liste. Geben Sie die Adressen in EmailList, getrennt durch Semikolons, an.

Beispiel: [email protected];[email protected];[email protected]

Dieser Endpunkt importiert ausschließlich E-Mail-Adressen. Wenn Sie auch benutzerdefinierte Feldwerte setzen möchten, verwenden Sie stattdessen /email/addSingle für jeden Kontakt.

Zuvor abgemeldete Adressen werden stillschweigend übersprungen, sofern Force=1 nicht gesetzt ist.

Listenauswahl: Geben Sie ListId (oder den veralteten Alias AddressBookId) an. Mindestens einer ist erforderlich.

OAuth-Scope : contacts:write

Parameter

Name	Ort	Typ	Erforderlich	Beschreibung
`format`	path	string: json, xml	ja	Antwortformat

Anfragetext (application/x-www-form-urlencoded)

Name	Typ	Erforderlich	Beschreibung
`ListId`	integer		Kennung der Zielliste. Der veraltete Alias `AddressBookId` wird ebenfalls akzeptiert.
`EmailList`	string	ja	Durch Semikolons getrennte zu importierende E-Mail-Adressen
`Force`	integer: 0, 1		Auf `1` setzen, um zuvor abgemeldete Adressen erneut zu importieren. Standard: `0` (abgemeldete Adressen werden übersprungen).

Antworten

Code	Beschreibung
`200`	Kontakte erfolgreich importiert
`400`	Fehlende EmailList
`401`	Ungültige Zugangsdaten

Beispiel 200

{
  "Result": "3 contacts imported"
}

POST `/email/addSingle.{format}`

Einzelnen Kontakt hinzufügen

Fügt einer Liste einen einzelnen Kontakt mit optionalen benutzerdefinierten Feldwerten hinzu.

Field1 bis Field25 entsprechen den benutzerdefinierten Spaltendefinitionen Ihrer Liste. Die Zuordnung hängt von der Reihenfolge ab, in der die Spalten definiert wurden — prüfen Sie in den Listeneinstellungen in der Mailpro-Oberfläche, welche Feldnummer welcher Spalte entspricht (z. B. Field1 = Vorname, Field2 = Nachname, Field3 = Stadt …).

Listenauswahl: Geben Sie ListId (oder den veralteten Alias AddressBookId) an.

OAuth-Scope : contacts:write

Parameter

Name	Ort	Typ	Erforderlich	Beschreibung
`format`	path	string: json, xml	ja	Antwortformat

Anfragetext (application/x-www-form-urlencoded)

Name	Typ	Erforderlich	Beschreibung
`ListId`	integer		Kennung der Zielliste. Der veraltete Alias `AddressBookId` wird ebenfalls akzeptiert.
`Email`	string	ja	E-Mail-Adresse des neuen Kontakts
`Force`	integer: 0, 1		Auf `1` setzen, um eine zuvor abgemeldete Adresse erneut hinzuzufügen
`Field1`	string		Wert für benutzerdefiniertes Feld 1 (Spaltenzuordnung abhängig von Ihrer Liste)
`Field2`	string		Wert für benutzerdefiniertes Feld 2
`Field3`	string		Wert für benutzerdefiniertes Feld 3
`Field4`	string		Wert für benutzerdefiniertes Feld 4
`Field5`	string		Wert für benutzerdefiniertes Feld 5

Antworten

Code	Beschreibung
`200`	Kontakt erfolgreich hinzugefügt
`400`	Fehlende E-Mail
`401`	Ungültige Zugangsdaten

Beispiel 200

{
  "EmailId": 10002,
  "Email": "[email protected]",
  "Field1": "Alice",
  "Field2": "Dupont",
  "ListID": 101
}

POST `/email/edit.{format}`

Kontakt aktualisieren

Aktualisiert die E-Mail-Adresse und/oder die benutzerdefinierten Feldwerte eines bestehenden Kontakts. Identifizieren Sie den Kontakt anhand der EmailId (aus /email/list). Sowohl EmailId als auch Email sind erforderlich.

OAuth-Scope : contacts:write

Parameter

Name	Ort	Typ	Erforderlich	Beschreibung
`format`	path	string: json, xml	ja	Antwortformat

Anfragetext (application/x-www-form-urlencoded)

Name	Typ	Erforderlich	Beschreibung
`EmailId`	integer	ja	Kennung des zu aktualisierenden Kontakts (aus `/email/list`)
`Email`	string	ja	Neue E-Mail-Adresse für den Kontakt
`Field1`	string		Neuer Wert für benutzerdefiniertes Feld 1
`Field2`	string		Neuer Wert für benutzerdefiniertes Feld 2
`Field3`	string		Neuer Wert für benutzerdefiniertes Feld 3

Antworten

Code	Beschreibung
`200`	Kontakt erfolgreich aktualisiert
`400`	Fehlende EmailId oder fehlende E-Mail
`401`	Ungültige Zugangsdaten
`404`	Kontakt nicht gefunden

POST `/email/del.{format}`

Kontakt löschen

Löscht einen Kontakt anhand seiner eindeutigen Kennung dauerhaft.

OAuth-Scope : contacts:write

Parameter

Name	Ort	Typ	Erforderlich	Beschreibung
`format`	path	string: json, xml	ja	Antwortformat

Anfragetext (application/x-www-form-urlencoded)

Name	Typ	Erforderlich	Beschreibung
`EmailId`	integer	ja	Kennung des zu löschenden Kontakts (aus `/email/list`)

Antworten

Code	Beschreibung
`200`	Kontakt erfolgreich gelöscht
`400`	Fehlende EmailId
`401`	Ungültige Zugangsdaten
`404`	Kontakt nicht gefunden

Messages

Verwalten Sie HTML-E-Mail-Vorlagen. Eine Nachrichtenvorlage speichert Ihren E-Mail-Betreff, den HTML-Body und die Konfiguration des Abmeldelinks. Vorlagen werden über mehrere Kampagnen hinweg wiederverwendet.

GET `/message/list.{format}`

Nachrichtenvorlagen auflisten

Gibt die gespeicherten HTML-E-Mail-Vorlagen des Kontos zurück. Standardmäßig ist der HTML-Body nicht in der Antwort enthalten, um die Payload klein zu halten. Setzen Sie bodyHTML=true, um ihn einzuschließen (die Ergebnisse werden dann automatisch auf 10 pro Seite begrenzt).

OAuth-Scope : email:templates:read

Parameter

Name	Ort	Typ	Erforderlich	Beschreibung
`format`	path	string: json, xml	ja	Antwortformat
`subjectFilter`	query	string		Nach Betreff filtern (teilweise, Groß-/Kleinschreibung ignorierend)
`numberOfRecords`	query	integer		Einträge pro Seite — standardmäßig und maximal 5.000 (siehe Paginierung).
`pageNumber`	query	integer		Seitennummer (1-basiert). Standardwert ist 1.
`bodyHTML`	query	boolean		Auf `true` setzen, um den vollständigen HTML-Body in jedes Ergebnis aufzunehmen. Bei `true` werden die Ergebnisse unabhängig von `numberOfRecords` automatisch auf 10 pro Seite begrenzt.

Antworten

Code	Beschreibung
`200`	Nachrichtenvorlagen erfolgreich zurückgegeben
`401`	Ungültige Zugangsdaten

Beispiel 200

{
  "MessageList": [
    {
      "IDMessage": 501,
      "Subject": "Spring Newsletter — April 2026",
      "Language": "EN",
      "LinkAlign": "center",
      "LinkUp": 0,
      "UpdateDate": "2026-03-10T14:22:00"
    }
  ]
}

POST `/message/add.{format}`

Nachrichtenvorlage erstellen

Erstellt eine neue HTML-E-Mail-Vorlage. Die Vorlage speichert den Betreff, den HTML-Body und die Einstellungen des Abmeldelinks. Nach der Erstellung verwenden Sie die zurückgegebene IDMessage beim Starten einer Kampagne.

OAuth-Scope : email:templates:write

Parameter

Name	Ort	Typ	Erforderlich	Beschreibung
`format`	path	string: json, xml	ja	Antwortformat

Anfragetext (application/x-www-form-urlencoded)

Name	Typ	Erforderlich	Beschreibung
`Subject`	string	ja	Betreffzeile der E-Mail (max. 255 Zeichen)
`BodyHTML`	string	ja	Vollständiger HTML-Inhalt des E-Mail-Bodys
`Language`	string	ja	Sprachcode für die Lokalisierung des Abmeldelinks (z. B. `EN`, `FR`, `DE`)
`LinkAlign`	string: left, center, right	ja	Horizontale Ausrichtung des Abmeldelinks
`LinkUp`	integer: 0, 1	ja	Position des Abmeldelinks — `0` = unten in der E-Mail, `1` = oben

Antworten

Code	Beschreibung
`200`	Nachrichtenvorlage erfolgreich erstellt
`400`	Fehlendes Pflichtfeld
`401`	Ungültige Zugangsdaten

Beispiel 200

{
  "IDMessage": 502,
  "Subject": "Spring Newsletter — April 2026",
  "Language": "EN",
  "LinkAlign": "center",
  "LinkUp": 0
}

POST `/message/edit.{format}`

Nachrichtenvorlage aktualisieren

Aktualisiert den Inhalt und die Metadaten einer bestehenden Nachrichtenvorlage.

OAuth-Scope : email:templates:write

Parameter

Name	Ort	Typ	Erforderlich	Beschreibung
`format`	path	string: json, xml	ja	Antwortformat

Anfragetext (application/x-www-form-urlencoded)

Name	Typ	Erforderlich	Beschreibung
`MessageId`	integer	ja	Kennung der zu aktualisierenden Nachrichtenvorlage (aus `/message/list`)
`Subject`	string	ja	Neue Betreffzeile der E-Mail
`BodyHTML`	string	ja	Neuer HTML-Inhalt des E-Mail-Bodys
`Language`	string	ja	Sprachcode für die Lokalisierung des Abmeldelinks
`LinkAlign`	string: left, center, right	ja
`LinkUp`	integer: 0, 1	ja

Antworten

Code	Beschreibung
`200`	Nachrichtenvorlage erfolgreich aktualisiert
`400`	Fehlendes Pflichtfeld
`401`	Ungültige Zugangsdaten
`404`	Nachrichtenvorlage nicht gefunden

POST `/message/del.{format}`

Nachrichtenvorlage löschen

Löscht eine Nachrichtenvorlage anhand ihrer eindeutigen Kennung dauerhaft. Vorlagen, die von ausstehenden geplanten Kampagnen verwendet werden, können nicht gelöscht werden.

OAuth-Scope : email:templates:write

Parameter

Name	Ort	Typ	Erforderlich	Beschreibung
`format`	path	string: json, xml	ja	Antwortformat

Anfragetext (application/x-www-form-urlencoded)

Name	Typ	Erforderlich	Beschreibung
`MessageId`	integer	ja	Kennung der zu löschenden Nachrichtenvorlage (aus `/message/list`)

Antworten

Code	Beschreibung
`200`	Nachrichtenvorlage erfolgreich gelöscht
`400`	Fehlende MessageId
`401`	Ungültige Zugangsdaten
`404`	Nachrichtenvorlage nicht gefunden

Campaigns

Versenden Sie E-Mail-Massenkampagnen an eine Liste und verwalten Sie geplante Versendungen. Eine Kampagne verwendet eine Nachrichtenvorlage und eine Absenderadresse.

GET `/send/list.{format}`

Geplante Kampagnen auflisten

Gibt die Liste der geplanten und kürzlich verarbeiteten E-Mail-Kampagnen zurück. Die Ergebnisse sind nach geplantem Versanddatum (neueste zuerst) sortiert.

OAuth-Scope : email:send

Parameter

Name	Ort	Typ	Erforderlich	Beschreibung
`format`	path	string: json, xml	ja	Antwortformat
`subjectMessageFilter`	query	string		Nach Kampagnenbetreff filtern (teilweise, Groß-/Kleinschreibung ignorierend)
`numberOfRecords`	query	integer		Einträge pro Seite — standardmäßig und maximal 5.000 (siehe Paginierung).
`pageNumber`	query	integer		Seitennummer (1-basiert). Standardwert ist 1.

Antworten

Code	Beschreibung
`200`	Kampagnenliste erfolgreich zurückgegeben
`401`	Ungültige Zugangsdaten

Beispiel 200

{
  "sends": [
    {
      "IDSend": 3001,
      "ListID": 101,
      "SenderEmail": "[email protected]",
      "SenderName": "Your Company Newsletter",
      "DatePlanned": "2026-04-20T09:00:00",
      "SubjectMessage": "Spring Newsletter — April 2026",
      "NumberCredit": 4521
    }
  ]
}

POST `/send/campaign.{format}`

Kampagne starten

Plant oder versendet sofort eine E-Mail-Kampagne an eine Liste unter Verwendung einer gespeicherten Nachrichtenvorlage und einer Absenderadresse.

Erforderlich:

IDMessage — die zu versendende Vorlage (aus /message/list)
IDEmailExp — die zu verwendende Absenderadresse (aus /senderEmail/list)
ListId — die Empfängerliste (aus /list/list). Der veraltete Alias IDAddressBook wird ebenfalls akzeptiert.

Planung: Setzen Sie DatePlanned auf ein zukünftiges ISO-8601-Datum/-Uhrzeit, um den Versand zu planen. Lassen Sie DatePlanned weg, um sofort zu versenden.

Statistik-Tracking: Setzen Sie Campaign=1 und geben Sie einen TitleCampaign an, um die Verfolgung von Öffnungen/Klicks/Bounces im Abschnitt Statistik zu aktivieren.

OAuth-Scope : email:send

Parameter

Name	Ort	Typ	Erforderlich	Beschreibung
`format`	path	string: json, xml	ja	Antwortformat

Anfragetext (application/x-www-form-urlencoded)

Name	Typ	Erforderlich	Beschreibung
`ListId`	integer		Kennung der Empfängerliste (aus `/list/list`). Der veraltete Alias `IDAddressBook` wird ebenfalls akzeptiert.
`IDMessage`	integer	ja	Kennung der zu versendenden Nachrichtenvorlage (aus `/message/list`)
`IDEmailExp`	integer	ja	Kennung der zu verwendenden Absender-E-Mail-Adresse (aus `/senderEmail/list`)
`IDUnsubscribeList`	integer		Liste, die zum Sammeln abgemeldeter Kontakte verwendet wird (Sperrliste). Der veraltete Alias `IDUnsubscribeAddressBook` wird ebenfalls akzeptiert.
`DatePlanned`	string (date-time)		Geplantes Versanddatum/-uhrzeit (ISO 8601). Weglassen, um sofort zu versenden.
`Campaign`	integer: 0, 1		Auf `1` setzen, um diesen Versand in den Statistiken als benannte Kampagne zu verfolgen
`TitleCampaign`	string		In den Statistiken angezeigter Kampagnentitel (erforderlich bei `Campaign=1`)

Antworten

Code	Beschreibung
`200`	Kampagne erfolgreich geplant oder versendet. > Die Antwort enthält außerdem die veralteten Aliase `AddressBookID` und `UnsubscribeAddressBookID` (identisch mit `ListID` / `UnsubscribeListID`). Neue Integrationen sollten diese ignorieren.
`400`	Fehlende IDMessage oder IDEmailExp
`401`	Ungültige Zugangsdaten
`403`	Nicht genügend E-Mail-Credits
`404`	Liste, Nachricht oder Absender nicht gefunden

Beispiel 200

{
  "send": {
    "IDSend": 3002,
    "ListID": 101,
    "UnsubscribeListID": 102,
    "IDCampaign": 8001,
    "SenderName": "Your Company Newsletter",
    "SenderEmail": "[email protected]",
    "DatePlanned": "2026-04-20T09:00:00",
    "SubjectMessage": "Spring Newsletter — April 2026",
    "NumberCredit": 4521
  }
}

POST `/send/del.{format}`

Kampagne stornieren oder löschen

Storniert einen ausstehenden geplanten Kampagnenversand oder löscht einen abgeschlossenen Versand. Nur zukünftig geplante Versendungen können storniert werden — laufende Versendungen können nicht gestoppt werden.

OAuth-Scope : email:send

Parameter

Name	Ort	Typ	Erforderlich	Beschreibung
`format`	path	string: json, xml	ja	Antwortformat

Anfragetext (application/x-www-form-urlencoded)

Name	Typ	Erforderlich	Beschreibung
`IdSend`	integer	ja	Kennung des zu stornierenden oder zu löschenden Kampagnenversands (aus `/send/list`)

Antworten

Code	Beschreibung
`200`	Kampagne erfolgreich storniert oder gelöscht
`400`	Fehlende IdSend
`401`	Ungültige Zugangsdaten
`404`	Kampagne nicht gefunden

Beispiel 200

{
  "Result": "Campaign Deleted"
}

GET `/send/scheduled.{format}`

Meine geplanten E-Mail-Kampagnen auflisten

Gibt die E-Mail-Kampagnen und Einzelversendungen zurück, die für ein zukünftiges Datum geplant und noch nicht versendet wurden. Nützlich vor dem Aufruf von /cancel oder /reschedule. Die Datensätze sind aufsteigend nach DatePlanned sortiert.

OAuth-Scope : email:send

Parameter

Name	Ort	Typ	Erforderlich	Beschreibung
`format`	path	string: json, xml	ja	Antwortformat
`numberOfRecords`	query	integer		Einträge pro Seite — standardmäßig und maximal 5.000 (siehe Paginierung).
`pageNumber`	query	integer		Seitennummer (1-basiert). Standardwert ist 1.

Antworten

Code	Beschreibung
`200`	Liste der geplanten Kampagnen/Versendungen. > Jeder Datensatz enthält außerdem die veralteten Aliase `AddressBookID` und > `UnsubscribeAddressBookID` (identisch mit `ListID` / `UnsubscribeListID`).
`401`	Ungültige Zugangsdaten

Beispiel 200

{
  "sends": [
    {
      "IDSend": 5001,
      "ListID": 101,
      "UnsubscribeListID": 102,
      "IDCampaign": 8001,
      "SenderName": "Your Company Newsletter",
      "SenderEmail": "[email protected]",
      "DatePlanned": "2026-05-01T09:00:00",
      "SubjectMessage": "Spring Sale 2026",
      "NumberCredit": 4521
    }
  ]
}

POST `/send/{IdSend}/cancel.{format}`

Geplante Kampagne/Versendung stornieren

Storniert einen geplanten E-Mail-Versand (Kampagne oder Einzelversand), der noch nicht versendet wurde. Wurde der Versand bereits ausgeführt (oder existiert nicht / gehört einem anderen Kunden), wird 409 Conflict zurückgegeben.

OAuth-Scope : email:send

Parameter

Name	Ort	Typ	Erforderlich	Beschreibung
`format`	path	string: json, xml	ja	Antwortformat
`IdSend`	path	integer	ja

Antworten

Code	Beschreibung
`200`	Versand storniert
`401`	Ungültige Zugangsdaten
`409`	Bereits versendet oder nicht gefunden

Beispiel 200

{
  "Result": "OK",
  "Cancelled": 5001
}

PATCH `/send/{IdSend}/reschedule.{format}`

Geplante Kampagne/Versendung neu planen

Aktualisiert das DatePlanned eines geplanten E-Mail-Versands. Das neue Datum muss in der Zukunft und innerhalb von 90 Tagen liegen.

OAuth-Scope : email:send

Parameter

Name	Ort	Typ	Erforderlich	Beschreibung
`format`	path	string: json, xml	ja	Antwortformat
`IdSend`	path	integer	ja

Anfragetext (application/x-www-form-urlencoded)

Name	Typ	Erforderlich	Beschreibung
`PlanDate`	string (date-time)	ja

Antworten

Code	Beschreibung
`200`	Versand neu geplant
`400`	Fehlendes oder ungültiges PlanDate
`401`	Ungültige Zugangsdaten
`409`	Bereits versendet, nicht gefunden oder neues Datum außerhalb des zulässigen Bereichs (muss in der Zukunft und innerhalb von 90 Tagen liegen)

Beispiel 200

{
  "Result": "OK",
  "IdSend": 5001,
  "NewPlanDate": "2026-12-31T14:30:00"
}

POST `/send/sendingTest.{format}`

Test-E-Mail versenden

Sendet eine Vorschau einer Nachrichtenvorlage an einen angegebenen Empfänger zur Überprüfung vor dem Start der eigentlichen Kampagne. Absender, Vorlage und Testempfänger werden jeweils über ihre Kennungen identifiziert.

OAuth-Scope : email:send

Parameter

Name	Ort	Typ	Erforderlich	Beschreibung
`format`	path	string: json, xml	ja	Antwortformat

Anfragetext (application/x-www-form-urlencoded)

Name	Typ	Erforderlich	Beschreibung
`MessageId`	integer	ja	Kennung der Nachrichtenvorlage für die Vorschau (aus `/message/list`)
`IDEmailExpFrom`	integer	ja	Kennung der zu verwendenden Absenderadresse (aus `/senderEmail/list`)
`IDEmailExpTo`	integer	ja	Kennung der Empfänger-Absenderadresse — die Test-E-Mail wird an diese Adresse gesendet

Antworten

Code	Beschreibung
`200`	Test-E-Mail erfolgreich versendet
`400`	Fehlendes Pflichtfeld
`401`	Ungültige Zugangsdaten

Beispiel 200

{
  "SendingTest": {
    "IdSendingTest": 7001,
    "ToEmail": "[email protected]",
    "FromEmail": "[email protected]",
    "SenderName": "Your Company Newsletter"
  }
}

Transactional

Versenden Sie einmalige transaktionale E-Mails an einzelne Empfänger. Im Gegensatz zu Kampagnen erfordern transaktionale E-Mails keine Liste — Sie übergeben die Empfänger-E-Mail-Adresse und den HTML-Body direkt.

GET `/send/mail/scheduled.{format}`

Geplante Einzel-E-Mails auflisten

Gibt die mit /send/sendmail und einem zukünftigen Datum gesendeten Einzel-E-Mails zurück, die noch nicht versendet wurden. Kampagnen werden von /send/scheduled aufgelistet.

OAuth-Scope : email:send

Parameter

Name	Ort	Typ	Erforderlich	Beschreibung
`format`	path	string: json, xml	ja	Antwortformat

Antworten

Code	Beschreibung
`200`	Geplante E-Mails zurückgegeben
`401`	Ungültige Zugangsdaten

Beispiel 200

{
  "scheduledMails": [
    {
      "IdSingleSend": 880123,
      "Email": "[email protected]",
      "Subject": "Your invoice",
      "DatePlanned": "2026-12-01T09:00:00"
    }
  ]
}

POST `/send/mail/{IdSingleSend}/cancel.{format}`

Geplante Einzel-E-Mail stornieren

Storniert die E-Mail, solange sie noch nicht versendet wurde.

OAuth-Scope : email:send

Parameter

Name	Ort	Typ	Erforderlich	Beschreibung
`format`	path	string: json, xml	ja	Antwortformat
`IdSingleSend`	path	integer (int64)	ja	Von `/send/sendmail` zurückgegebene `IdSingleSend`

Antworten

Code	Beschreibung
`200`	E-Mail storniert
`401`	Ungültige Zugangsdaten
`409`	Versand nicht gefunden oder bereits erfolgt

Beispiel 200

{
  "Result": "OK",
  "Cancelled": 880123
}

POST `/send/mail/{IdSingleSend}/reschedule.{format}`

Geplante Einzel-E-Mail neu planen

Ändert das Versanddatum. Das neue Datum muss in der Zukunft und innerhalb von 90 Tagen liegen. PATCH wird ebenfalls akzeptiert.

OAuth-Scope : email:send

Parameter

Name	Ort	Typ	Erforderlich	Beschreibung
`format`	path	string: json, xml	ja	Antwortformat
`IdSingleSend`	path	integer (int64)	ja	Von `/send/sendmail` zurückgegebene `IdSingleSend`

Anfragetext (application/x-www-form-urlencoded)

Name	Typ	Erforderlich	Beschreibung
`PlanDate`	string (date-time)	ja	Neues Versanddatum (ISO 8601)

Antworten

Code	Beschreibung
`200`	E-Mail neu geplant
`400`	Datum fehlt oder ist ungültig
`401`	Ungültige Zugangsdaten
`409`	Versand nicht gefunden, bereits erfolgt oder Datum außerhalb des zulässigen Bereichs

Beispiel 200

{
  "Result": "OK",
  "IdSingleSend": 880123,
  "NewPlanDate": "2026-12-15T09:00:00"
}

POST `/send/sendmail.{format}`

Transaktionale E-Mail versenden

Versendet eine einmalige transaktionale E-Mail an einen oder mehrere Empfänger. Im Gegensatz zu Kampagnen erfordert dieser Endpunkt keine Liste — die Empfängeradresse und der HTML-Body werden direkt übergeben.

Erforderlich:

IDEmailExp — die Kennung der Absenderadresse (aus /senderEmail/list)
EmailData — Empfänger im Format email,field1,field2,...,field25 (durch Kommas getrennt)
BodyHTML — der HTML-Body
Subject — die Betreffzeile

EmailData-Format: [email protected],Alice,Dupont,Paris Der erste Wert ist die E-Mail-Adresse; die Werte 2–26 entsprechen den Feldern Field1–Field25 für Personalisierungsvariablen in Ihrer HTML-Vorlage.

Mehrere Empfänger: Trennen Sie mehrere EmailData-Einträge mit Semikolons: [email protected],Alice;[email protected],Bob

Planung: Setzen Sie DatePlanned auf ein zukünftiges ISO-8601-Datum/-Uhrzeit, oder lassen Sie es weg, um sofort zu versenden.

OAuth-Scope : email:send

Parameter

Name	Ort	Typ	Erforderlich	Beschreibung
`format`	path	string: json, xml	ja	Antwortformat

Anfragetext (multipart/form-data)

Name	Typ	Erforderlich	Beschreibung
`IDEmailExp`	integer	ja	Kennung der zu verwendenden Absender-E-Mail-Adresse (aus `/senderEmail/list`)
`EmailData`	string	ja	Empfänger im Format `email,feld1,feld2,...,feld25` (kommagetrennt). Der erste Wert ist die E-Mail-Adresse; die übrigen sind Personalisierungsfelder, die Field1–Field25 in Ihrer HTML-Vorlage zugeordnet werden. Der lokale Teil der E-Mail (vor dem `@`) akzeptiert Buchstaben, Ziffern und `. _ - +` — einschließlich RFC-5322-Sub-Addressing (`user+tag@domain`, z. B. Gmail, Fastmail, Proton). Andere von RFC 5322 erlaubte Sonderzeichen (z. B. `! # $ % & ' * / = ? ^ { \| } ~`) sowie lokale Teile in Anführungszeichen werden nicht akzeptiert.
`BodyHTML`	string	ja	Vollständiger HTML-Inhalt des E-Mail-Bodys
`Subject`	string	ja	Betreffzeile der E-Mail (max. 255 Zeichen)
`attachments`	array of string (binary)		Optionale Dateianhänge — senden Sie die Anfrage als `multipart/form-data` und fügen Sie pro Anhang einen Dateiteil hinzu (beliebiger Feldname). Bis zu 5 Dateien, 10 MB pro Datei, 15 MB insgesamt. Zulässige Typen: PDF, Word, Excel, PowerPoint, Bilder (JPG, PNG, GIF, WebP), ZIP, CSV, TXT — ausführbare Dateien und Skripte werden abgelehnt. Abrechnung: der Versand behält sein übliches 1 Guthaben, plus 1 Guthaben pro 512 KB Anhänge über die ersten 512 KB hinaus (Anhänge ≤ 512 KB kosten nichts extra). Alle anderen Felder dieses Endpunkts (`ReplyTo`, `ActivateStatistics`, `CustomHeaders`, …) funktionieren genau wie in der form-urlencoded-Variante.
`KeepInMyFiles`	boolean		`false` (Standard): Die Anhänge werden nur für diesen Versand verwendet — sie werden außerhalb Ihres Kontos gespeichert, zählen nicht zu Ihrem Speicherkontingent und werden nach 35 Tagen automatisch gelöscht. `true`: Die Anhänge werden zusätzlich in den Dateien Ihres Kontos gespeichert (Ordner `Secure/Files/Sending/api`) und zählen zu Ihrem Speicherkontingent.

Antworten

Code	Beschreibung
`200`	Transaktionale E-Mail erfolgreich versendet oder geplant
`400`	Fehlendes Pflichtfeld oder ungültiges E-Mail-Format
`401`	Ungültige Zugangsdaten
`403`	Nicht genügend E-Mail-Credits
`404`	Absender nicht gefunden oder E-Mail-Adresse abgemeldet

Beispiel 200

{
  "SingleSend": {
    "IdSingleSend": 8001,
    "IdEmailExp": 201,
    "DatePlanned": "2026-04-15T14:30:00",
    "Subject": "Your order #12345 is confirmed",
    "Email": "[email protected]",
    "Field1": "Alice",
    "Field2": "Dupont",
    "UnsubscriptionLink": false,
    "ActivateStatistics": true
  }
}

GET `/send/{IdSend}/status.{format}`

Zustellstatus einer transaktionalen E-Mail abrufen

Gibt den aktuellen Zustellstatus einer transaktionalen E-Mail zurück, die über /send/sendmail gesendet wurde. Übergeben Sie die IdSingleSend, die dieser Aufruf zurückgegeben hat.

Mögliche Werte: delivered (vom Empfängerserver angenommen, siehe DiagCode), bounced (abgelehnt — BounceType: hard ungültige Adresse oder endgültige Ablehnung, soft Ablehnung nach erneuten Versuchen), sent (an den Mailserver übergeben, noch keine Antwort), scheduled (noch nicht gesendet, DatePlanned in der Zukunft) und queued (wartet auf den Versand). delivered und bounced sind endgültig: Beenden Sie die Abfragen. Jede E-Mail hat spätestens 48 Stunden nach dem Versand einen endgültigen Status; fragen Sie höchstens alle 15 Minuten ab (jeder Aufruf zählt für Ihr API-Kontingent) oder nutzen Sie die Webhooks email.delivered / email.bounced. Nur der Kunde, der die E-Mail gesendet hat, kann ihren Status lesen — jede andere ID liefert 404.

OAuth-Scope : email:read

Parameter

Name	Ort	Typ	Erforderlich	Beschreibung
`format`	path	string: json, xml	ja	Antwortformat
`IdSend`	path	integer	ja	Die von `/send/sendmail` zurückgegebene `IdSingleSend`.

Antworten

Code	Beschreibung
`200`	Aktueller Zustellstatus
`401`	Ungültige Zugangsdaten
`404`	Kein transaktionaler Versand mit dieser ID für diesen Kunden gefunden

Beispiel 200

{
  "status": {
    "IdSingleSend": 8001,
    "Email": "[email protected]",
    "Status": "delivered",
    "DatePlanned": "2026-04-15T14:30:00",
    "StatusDate": "2026-04-15T14:30:07",
    "DiagCode": "2.0.0 (success)",
    "BounceType": null
  }
}

Sender Addresses

Auflistung und Verwaltung validierter Absender-E-Mail-Adressen. Nur verifizierte Adressen können als From-Adresse in Kampagnen verwendet werden.

GET `/senderEmail/list.{format}`

Validierte Absenderadressen auflisten

Gibt die Liste der für das Konto konfigurierten Absender-E-Mail-Adressen zurück. Nur Adressen mit IsValid: true können beim Versenden von Kampagnen verwendet werden. Neue Adressen werden mit /senderEmail/add hinzugefügt und sind gültig, sobald der Link in der Bestätigungs-E-Mail angeklickt wurde.

OAuth-Scope : email:templates:read

Parameter

Name	Ort	Typ	Erforderlich	Beschreibung
`format`	path	string: json, xml	ja	Antwortformat
`emailFilter`	query	string		Nach E-Mail-Adresse filtern (teilweise, Groß-/Kleinschreibung ignorierend)
`numberOfRecords`	query	integer		Einträge pro Seite — standardmäßig und maximal 5.000 (siehe Paginierung).
`pageNumber`	query	integer		Seitennummer (1-basiert). Standardwert ist 1.
`sortByName`	query	boolean		Auf `true` setzen, um die Ergebnisse alphabetisch nach Absendername zu sortieren

Antworten

Code	Beschreibung
`200`	Absenderadressen erfolgreich zurückgegeben
`401`	Ungültige Zugangsdaten

Beispiel 200

{
  "ExpEmailList": [
    {
      "IDEmailExp": 201,
      "Email": "[email protected]",
      "SenderName": "Your Company Newsletter",
      "IsValid": true,
      "CreationDate": "2025-06-01T09:00:00"
    },
    {
      "IDEmailExp": 202,
      "Email": "[email protected]",
      "SenderName": "Your Company Support",
      "IsValid": true,
      "CreationDate": "2025-06-01T09:05:00"
    }
  ]
}

POST `/senderEmail/add.{format}`

Absenderadresse hinzufügen

Fügt die Adresse mit denselben Prüfungen wie in der Anwendung hinzu und sendet ihr eine Bestätigungs-E-Mail. Sie kann verwendet werden, sobald der Link in dieser E-Mail angeklickt wurde. Ein Konto kann bis zu 25 Absender haben, bestätigt oder ausstehend.

OAuth-Scope : email:templates:write

Parameter

Name	Ort	Typ	Erforderlich	Beschreibung
`format`	path	string: json, xml	ja	Antwortformat

Anfragetext (application/x-www-form-urlencoded)

Name	Typ	Erforderlich	Beschreibung
`Email`	string	ja	Absenderadresse
`SenderName`	string	ja	Den Empfängern angezeigter Name

Antworten

Code	Beschreibung
`200`	Adresse hinzugefügt. `DomainHasMx` ist false, wenn die Domain keinen MX-Eintrag hat.
`400`	`Email` oder `SenderName` fehlt
`401`	Ungültige Zugangsdaten
`422`	Adresse abgelehnt: ungültig, bereits unter den Absendern des Kontos, öffentliche E-Mail-Domain, unzulässiger Name oder Limit von 25 erreicht. Die Meldung nennt den Grund.
`503`	Vorübergehend nicht verfügbar, bitte versuchen Sie es erneut

Beispiel 200

{
  "Result": "OK",
  "ConfirmationSent": true,
  "DomainHasMx": true
}

POST `/senderEmail/{IdSenderEmail}/resendValidation.{format}`

Bestätigungs-E-Mail erneut senden

Für eine Adresse, die noch auf die Bestätigung wartet.

OAuth-Scope : email:templates:write

Parameter

Name	Ort	Typ	Erforderlich	Beschreibung
`format`	path	string: json, xml	ja	Antwortformat
`IdSenderEmail`	path	integer	ja	ID des Absenders aus `/senderEmail/list`

Antworten

Code	Beschreibung
`200`	E-Mail erneut gesendet
`401`	Ungültige Zugangsdaten
`404`	Absender nicht gefunden
`409`	Dieser Absender ist bereits bestätigt
`503`	Vorübergehend nicht verfügbar, bitte versuchen Sie es erneut

Beispiel 200

{
  "Result": "OK",
  "ConfirmationSent": true
}

GET `/senderEmail/{IdSenderEmail}/authentication.{format}`

Domain eines Absenders prüfen (SPF, DKIM, DMARC, MX)

Prüft die Domain live im DNS und gibt die zu veröffentlichenden Einträge zurück. Nur Lesezugriff. DKIM wird in der Anwendung aktiviert: DkimSettingsUrl öffnet die richtige Seite.

OAuth-Scope : email:templates:read

Parameter

Name	Ort	Typ	Erforderlich	Beschreibung
`format`	path	string: json, xml	ja	Antwortformat
`IdSenderEmail`	path	integer	ja	ID des Absenders aus `/senderEmail/list`

Antworten

Code	Beschreibung
`200`	Status der Domain. `Spf.RecommendedRecord` basiert auf Ihrem aktuellen Eintrag: Veröffentlichen Sie ihn nur, wenn `Spf.ChangeNeeded` true ist.
`401`	Ungültige Zugangsdaten
`404`	Absender nicht gefunden
`503`	Vorübergehend nicht verfügbar, bitte versuchen Sie es erneut

Beispiel 200

{
  "Domain": "example.com",
  "Spf": {
    "Valid": true,
    "Record": "v=spf1 include:spf.mailpro.com -all",
    "RecommendedRecord": "v=spf1 include:spf.mailpro.com -all",
    "ChangeNeeded": false
  },
  "Dkim": {
    "Valid": true,
    "Records": [
      {
        "Host": "key._domainkey.example.com",
        "Value": "v=DKIM1;k=rsa;p=MIIBIjANBgkq...",
        "Validated": true
      }
    ]
  },
  "Dmarc": {
    "Valid": true,
    "Record": "v=DMARC1; p=quarantine"
  },
  "Mx": {
    "Valid": true,
    "Record": "mail.example.com"
  },
  "DkimSettingsUrl": "https://app.mailpro.com/dkim/list?d=example.com"
}

POST `/senderEmail/del.{format}`

Absenderadresse entfernen

Entfernt eine validierte Absender-E-Mail-Adresse aus dem Konto. Absenderadressen, die von geplanten Kampagnen verwendet werden, können nicht gelöscht werden.

OAuth-Scope : email:templates:write

Parameter

Name	Ort	Typ	Erforderlich	Beschreibung
`format`	path	string: json, xml	ja	Antwortformat

Anfragetext (application/x-www-form-urlencoded)

Name	Typ	Erforderlich	Beschreibung
`idEmailExp`	integer	ja	Kennung der zu entfernenden Absenderadresse (aus `/senderEmail/list`)

Antworten

Code	Beschreibung
`200`	Absenderadresse erfolgreich entfernt
`400`	Fehlende idEmailExp
`401`	Ungültige Zugangsdaten

Beispiel 200

{
  "Result": "EmailSender Deleted"
}

Statistics

Zugriff auf Leistungskennzahlen pro Kampagne: Öffnungen, Klicks, Bounces und mehr. Detaillierte Aufschlüsselungen nach Stunde, Tag, Land, Betriebssystem und E-Mail-Client sind verfügbar.

GET `/stats/list.{format}`

Kampagnenstatistiken auflisten

Gibt Gesamtleistungskennzahlen für alle Kampagnen zurück: Anzahl der Versendungen, Öffnungsrate, Klickrate, Anzahl der Bounces. Filtern Sie nach Datumsbereich oder Kampagnentitel. Die Ergebnisse sind nach Versanddatum (neueste zuerst) sortiert.

OAuth-Scope : email:read

Parameter

Name	Ort	Typ	Erforderlich	Beschreibung
`format`	path	string: json, xml	ja	Antwortformat
`titleCampaignFilter`	query	string		Nach Kampagnentitel filtern (teilweise, Groß-/Kleinschreibung ignorierend)
`numberOfRecords`	query	integer		Einträge pro Seite — standardmäßig und maximal 5.000 (siehe Paginierung).
`pageNumber`	query	integer		Seitennummer (1-basiert). Standardwert ist 1.
`dateStart`	query	string (date-time)		Beginn des Datumsbereichsfilters (ISO 8601)
`dateEnd`	query	string (date-time)		Ende des Datumsbereichsfilters (ISO 8601)

Antworten

Code	Beschreibung
`200`	Kampagnenstatistiken erfolgreich zurückgegeben
`401`	Ungültige Zugangsdaten

Beispiel 200

{
  "Campaigns": [
    {
      "IdCampaign": 8001,
      "DateCampaign": "2026-04-20T09:00:01",
      "TitleCampaign": "Spring Newsletter April 2026",
      "NumberEmailSend": 4521,
      "NumberEmailOpen": 1823,
      "NumberEmailClick": 342,
      "BadMail": 12,
      "NumberUnsubscribers": 8,
      "NumberComplaints": 1,
      "SpamTrap": 0,
      "DeliverabilityScore": 98
    }
  ]
}

GET `/stats/byHour.{format}`

Statistik nach Stunde

Gibt die stündliche Aufschlüsselung der Öffnungen und Klicks für eine bestimmte Kampagne zurück. Nützlich, um die optimale Versandzeit zu ermitteln.

OAuth-Scope : email:read

Parameter

Name	Ort	Typ	Erforderlich	Beschreibung
`format`	path	string: json, xml	ja	Antwortformat
`idCampaign`	query	integer	ja	Kennung der Kampagne (aus `/stats/list`)

Antworten

Code	Beschreibung
`200`	Stündliche Statistiken erfolgreich zurückgegeben
`401`	Ungültige Zugangsdaten

Beispiel 200

{
  "ByHour": [
    {
      "Hour": 9,
      "Opens": 823,
      "Clicks": 142
    },
    {
      "Hour": 10,
      "Opens": 512,
      "Clicks": 98
    }
  ]
}

POST `/stats/del.{format}`

Kampagnenstatistiken löschen

Löscht alle Statistikdatensätze für eine bestimmte Kampagne dauerhaft.

OAuth-Scope : email:templates:write

Parameter

Name	Ort	Typ	Erforderlich	Beschreibung
`format`	path	string: json, xml	ja	Antwortformat

Anfragetext (application/x-www-form-urlencoded)

Name	Typ	Erforderlich	Beschreibung
`IdCampaign`	integer	ja	Kennung der Kampagne, deren Statistiken gelöscht werden sollen (aus `/stats/list`)

Antworten

Code	Beschreibung
`200`	Kampagnenstatistiken erfolgreich gelöscht
`400`	Fehlende IdCampaign
`401`	Ungültige Zugangsdaten
`404`	Kampagne nicht gefunden

Beispiel 200

{
  "Result": "Statistic Deleted"
}

GET `/stats/open.{format}`

Protokoll der Öffnungsereignisse

Gibt das Protokoll der Öffnungsereignisse pro Empfänger für eine Kampagne zurück (eine Zeile pro Öffnung). Verwenden Sie emailFilter, um nach einem bestimmten Empfänger zu suchen (teilweise, Groß-/Kleinschreibung ignorierend).

OAuth-Scope : email:read

Parameter

Name	Ort	Typ	Erforderlich	Beschreibung
`format`	path	string: json, xml	ja	Antwortformat
`idCampaign`	query	integer	ja
`emailFilter`	query	string
`numberOfRecords`	query	integer		Einträge pro Seite — standardmäßig und maximal 5.000 (siehe Paginierung).
`pageNumber`	query	integer		Seitennummer (1-basiert). Standardwert ist 1.

Antworten

Code	Beschreibung
`200`	Öffnungsereignisse zurückgegeben
`401`	Ungültige Zugangsdaten

GET `/stats/click.{format}`

Protokoll der Klickereignisse

Gibt das Protokoll der Klickereignisse pro Empfänger für eine Kampagne zurück — einschließlich des angeklickten Links und des Zeitpunkts.

OAuth-Scope : email:read

Parameter

Name	Ort	Typ	Erforderlich	Beschreibung
`format`	path	string: json, xml	ja	Antwortformat
`idCampaign`	query	integer	ja
`emailFilter`	query	string
`numberOfRecords`	query	integer		Einträge pro Seite — standardmäßig und maximal 5.000 (siehe Paginierung).
`pageNumber`	query	integer		Seitennummer (1-basiert). Standardwert ist 1.

Antworten

Code	Beschreibung
`200`	Klickereignisse zurückgegeben
`401`	Ungültige Zugangsdaten

GET `/stats/bounce.{format}`

Bounce-Protokoll

Gibt die Liste der zurückgewiesenen Empfänger (Hard Bounces, Soft Bounces, Spam-Beschwerden) einer Kampagne zurück, mit dem Fehlergrund für jede Adresse.

OAuth-Scope : email:read

Parameter

Name	Ort	Typ	Erforderlich	Beschreibung
`format`	path	string: json, xml	ja	Antwortformat
`idCampaign`	query	integer	ja
`emailFilter`	query	string
`numberOfRecords`	query	integer		Einträge pro Seite — standardmäßig und maximal 5.000 (siehe Paginierung).
`pageNumber`	query	integer		Seitennummer (1-basiert). Standardwert ist 1.

Antworten

Code	Beschreibung
`200`	Zurückgegebene Bounce-Ereignisse
`401`	Ungültige Zugangsdaten

Beispiel 200

{
  "ListBadMail": [
    {
      "Email": "[email protected]",
      "Date": "2026-04-20T09:05:12",
      "Error": "550 5.1.1 recipient rejected",
      "AddressbookId": 1813318
    }
  ]
}

History

Durchsuchen Sie das vollständige Protokoll aller bisherigen E-Mail-Versendungen.

GET `/history/list.{format}`

Versandverlauf auflisten

Gibt ein paginiertes Protokoll aller bisherigen E-Mail-Versendungen zurück. Filtern Sie nach Kampagnenkennung oder nach Betreff. Setzen Sie bodyHTML=true, um den HTML-Body einzuschließen (begrenzt automatisch auf 10 pro Seite).

OAuth-Scope : email:read

Parameter

Name	Ort	Typ	Erforderlich	Beschreibung
`format`	path	string: json, xml	ja	Antwortformat
`subjectMessageFilter`	query	string		Nach Kampagnenbetreff filtern (teilweise, Groß-/Kleinschreibung ignorierend)
`idCampaign`	query	integer		Nur den Verlauf einer bestimmten Kampagne zurückgeben
`numberOfRecords`	query	integer		Einträge pro Seite — standardmäßig und maximal 5.000 (siehe Paginierung).
`pageNumber`	query	integer		Seitennummer (1-basiert). Standardwert ist 1.
`bodyHTML`	query	boolean		Auf `true` setzen, um den vollständigen HTML-Body einzuschließen. Begrenzt die Ergebnisse automatisch auf 10 pro Seite.

Antworten

Code	Beschreibung
`200`	Verlauf erfolgreich zurückgegeben
`401`	Ungültige Zugangsdaten

Beispiel 200

{
  "HistoricList": [
    {
      "IDHistoric": 9001,
      "SubjectMessage": "Spring Newsletter — April 2026",
      "DateSend": "2026-04-20T09:00:01",
      "NumberSend": 4521,
      "NumberOpen": 1823,
      "NumberClick": 342
    }
  ]
}

Import

Laden Sie eine CSV- oder XLSX-Datei hoch, um E-Mail-Kontakte in einem Schritt in eine Liste zu importieren. Die Datei wird zur asynchronen Verarbeitung in die Warteschlange gestellt — verfolgen Sie den Abschluss über die zurückgegebene ImportJobId oder über den optionalen Callback WebhookUrl.

POST `/import/upload.{format}`

Kontaktdatei (CSV/XLSX) für den Massenimport hochladen

Laden Sie eine CSV- oder XLSX-Datei hoch, um E-Mail-Kontakte in eine Liste zu importieren. Die Datei wird gespeichert und zur asynchronen Verarbeitung in die Warteschlange gestellt — der Endpunkt gibt sofort eine ImportJobId zurück.

Anfragetyp: multipart/form-data

Erforderliche Formularfelder:

IdClient (Ganzzahl) — Ihre Mailpro-Kundenkennung
ApiKey (Zeichenkette) — Ihr API-Schlüssel
ListId (Ganzzahl) — Kennung der Zielliste. Der veraltete Alias AddressBookId wird ebenfalls akzeptiert.
file (Binärdaten) — die hochzuladende CSV- oder XLSX-Datei

Optional:

WebhookUrl (Zeichenkette) — HTTPS-URL, die nach Abschluss der Verarbeitung aufgerufen wird. Empfängt eine JSON-Nutzlast mit dem endgültigen Status (erfolgreich/fehlgeschlagen) und der Anzahl der importierten/übersprungenen/ungültigen Zeilen.

Dateiformat:

UTF-8-kodiert
Erste Zeile = Kopfzeilen (eine davon muss Email lauten — Groß-/Kleinschreibung wird ignoriert)
Weitere Spalten werden auf benutzerdefinierte Felder der Zielliste abgebildet
Maximale Dateigröße: 50 MB

OAuth-Scope : contacts:write

Parameter

Name	Ort	Typ	Erforderlich	Beschreibung
`format`	path	string: json, xml	ja	Antwortformat

Anfragetext (multipart/form-data)

Name	Typ	Erforderlich	Beschreibung
`ListId`	integer	ja	Kennung der Zielliste. Der veraltete Alias `AddressBookId` wird ebenfalls akzeptiert.
`file`	string (binary)	ja	CSV- oder XLSX-Datei (`UTF-8`, max. 50 MB)
`WebhookUrl`	string (uri)		Callback-URL, die nach Abschluss der Verarbeitung aufgerufen wird

Antworten

Code	Beschreibung
`200`	Datei akzeptiert und in die Warteschlange gestellt
`400`	Keine Datei hochgeladen oder fehlende ListId
`401`	Ungültige Zugangsdaten
`500`	Server- oder Speicherfehler

Beispiel 200

{
  "Result": "OK",
  "ImportJobId": 13,
  "InternalName": "230575-20260420140221-contacts.csv"
}

Webhooks

Abonnieren Sie Echtzeit-Ereignisbenachrichtigungen für Ihren Server. Mailpro sendet eine HMAC-signierte JSON-Nutzlast per POST an Ihre URL, sobald das abonnierte Ereignis eintritt. Den vollständigen Ereigniskatalog, den Aufbau der Nutzlast, Code-Snippets zur Signaturprüfung und die Wiederholungsstrategie finden Sie im Abschnitt „Webhooks“ in der Einführung.

POST `/webhooks`

Webhook erstellen

Erstellt ein neues Webhook-Abonnement. Die Antwort enthält ein secret, das nur einmal angezeigt wird — speichern Sie es sofort serverseitig. Verwenden Sie es zur Überprüfung der HMAC-Signatur jeder eingehenden Nutzlast.

Grenzen: max. 20 Webhooks pro Konto, max. 50 Ereignisse pro Webhook.

Anfragetext (application/json)

Name	Typ	Erforderlich	Beschreibung
`url`	string (uri)	ja	HTTPS-Endpunkt (HTTP wird in der Produktion abgelehnt)
`events`	array of string	ja	Liste der zu abonnierenden Ereignistypen (siehe Katalog oben). Verwenden Sie `["*"]`, um alle Ereignisse dieser API zu abonnieren.
`description`	string

Beispiel

{
  "url": "https://example.com/hooks/mailpro",
  "events": [
    "email.delivered",
    "email.bounced"
  ],
  "description": "Slack-Integration"
}

Antworten

Code	Beschreibung
`201`	Webhook erstellt — das `secret` wird nur hier zurückgegeben
`400`	Ungültige URL, ungültige Ereignisliste oder Limit überschritten
`401`	Ungültige Zugangsdaten

Beispiel 201

{
  "id": 42,
  "url": "https://example.com/hooks/mailpro",
  "events": [
    "email.delivered",
    "email.bounced"
  ],
  "description": "Slack-Integration",
  "isActive": true,
  "consecutiveFailures": 0,
  "autoDisabledAt": null,
  "autoDisabledReason": null,
  "createdAt": "2026-05-25T10:00:00Z",
  "updatedAt": "2026-05-25T10:00:00Z",
  "secret": "whsec_AbcD1234EfgH5678IjkL9012MnoP3456QrsT"
}

PUT `/webhooks/{id}`

Webhook aktualisieren

Teilaktualisierung — nur die übermittelten Felder werden geändert.

Parameter

Name	Ort	Typ	Erforderlich	Beschreibung
`id`	path	integer (int64)	ja

Anfragetext (application/json)

Name	Typ	Beschreibung
`url`	string (uri)
`events`	array of string
`description`	string
`isActive`	boolean	Auf `true` setzen, um einen automatisch deaktivierten Webhook nach Behebung Ihres Endpunkts wieder zu aktivieren.

Antworten

Code	Beschreibung
`200`	Aktualisierter Webhook
`400`	Ungültige Nutzlast
`404`	Webhook nicht gefunden

POST `/webhooks/{id}/test`

Testereignis senden

Stellt ein sofortiges ping-Ereignis (oder jeden anderen Ereignistyp über das Body-Feld eventType) zur Zustellung an Ihren Endpunkt in die Warteschlange. Nützlich, um die Erreichbarkeit und die Signaturprüfung vor dem Einsatz für echte Ereignisse zu überprüfen.

Parameter

Name	Ort	Typ	Erforderlich	Beschreibung
`id`	path	integer (int64)	ja

Anfragetext (application/json)

Name	Typ	Erforderlich	Beschreibung
`eventType`	string

Beispiel

{
  "eventType": "ping"
}

Antworten

Code	Beschreibung
`202`	Ereignis zur Zustellung in die Warteschlange gestellt
`404`	Webhook nicht gefunden

Beispiel 202

{
  "deliveryId": 1234,
  "eventId": "evt_8f3a9b2c4d1e5f6789abcdef01234567",
  "eventType": "ping"
}

Suppression

GET `/suppression/bounces.{format}`

Bounces des Kontos auflisten

Die neuesten zuerst. Die Gesamtzahl steht im Header X-Total-Count.

OAuth-Scope : email:read

Parameter

Name	Ort	Typ	Erforderlich	Beschreibung
`format`	path	string: json, xml	ja	Antwortformat
`type`	query	string: hard, soft		`hard` oder `soft`
`source`	query	string		Herkunft des Bounces: `list`, `contact`, `api` oder `smtp`
`email`	query	string		Genaue Adresse
`dateFrom`	query	string (date-time)		Ab diesem Datum
`dateTo`	query	string (date-time)		Bis zu diesem Datum
`numberOfRecords`	query	integer
`pageNumber`	query	integer

Antworten

Code	Beschreibung
`200`	Bounces zurückgegeben
`400`	`type` muss `hard` oder `soft` sein
`401`	Ungültige Zugangsdaten

Beispiel 200

{
  "bounces": [
    {
      "Id": 5521,
      "Source": "contact",
      "BounceType": "hard",
      "Email": "[email protected]",
      "Date": "2026-10-12T08:30:00",
      "DiagCode": "550 5.1.1 User unknown",
      "IdList": 101
    }
  ]
}

POST `/suppression/bounces/{Id}/del.{format}`

Bounce entfernen

Source und Type sind erforderlich, wie von /suppression/bounces zurückgegeben: Eine Id allein ist nicht eindeutig.

OAuth-Scope : contacts:write

Parameter

Name	Ort	Typ	Erforderlich	Beschreibung
`format`	path	string: json, xml	ja	Antwortformat
`Id`	path	integer (int64)	ja	`Id` des Bounces

Anfragetext (application/x-www-form-urlencoded)

Name	Typ	Erforderlich	Beschreibung
`Source`	string	ja	`list`, `contact`, `api` oder `smtp`
`Type`	string: hard, soft	ja	`hard` oder `soft`

Antworten

Code	Beschreibung
`200`	Bounce entfernt
`400`	`Source` oder `Type` fehlt
`401`	Ungültige Zugangsdaten
`404`	Bounce nicht gefunden

Beispiel 200

{
  "Result": "OK",
  "Id": 5521,
  "Restored": false
}

POST `/suppression/bounces/{Id}/restore.{format}`

Kontakt mit Hard Bounce wieder in seine Listen aufnehmen

Nur für einen Hard Bounce mit der Herkunft contact.

OAuth-Scope : contacts:write

Parameter

Name	Ort	Typ	Erforderlich	Beschreibung
`format`	path	string: json, xml	ja	Antwortformat
`Id`	path	integer (int64)	ja	`Id` des Bounces

Antworten

Code	Beschreibung
`200`	Kontakt wieder aufgenommen
`401`	Ungültige Zugangsdaten
`404`	Hard Bounce eines Kontakts nicht gefunden oder Adresse nicht mehr aktiv

Beispiel 200

{
  "Result": "OK",
  "Id": 5521,
  "Restored": true
}

GET `/suppression/unsubscribers.{format}`

Abmeldungen des Kontos auflisten

Die neuesten zuerst. Die Gesamtzahl steht im Header X-Total-Count.

OAuth-Scope : contacts:read

Parameter

Name	Ort	Typ	Erforderlich	Beschreibung
`format`	path	string: json, xml	ja	Antwortformat
`source`	query	string		Herkunft der Abmeldung: `contact`, `list`, `smtp`, `api` oder `api3`
`email`	query	string		Genaue Adresse
`dateFrom`	query	string (date-time)		Ab diesem Datum
`dateTo`	query	string (date-time)		Bis zu diesem Datum
`numberOfRecords`	query	integer
`pageNumber`	query	integer

Antworten

Code	Beschreibung
`200`	Abmeldungen zurückgegeben
`401`	Ungültige Zugangsdaten

Beispiel 200

{
  "unsubscribers": [
    {
      "Id": 9012,
      "Source": "api",
      "Email": "[email protected]",
      "Date": "2026-10-20T16:05:00",
      "ListName": null,
      "Comment": "Asked by phone"
    }
  ]
}

POST `/suppression/unsubscribers/add.{format}`

Abmeldung hinzufügen

Ohne ListId wird die Adresse für das gesamte Konto abgemeldet. Mit ListId nur von dieser Abmeldeliste.

OAuth-Scope : contacts:write

Parameter

Name	Ort	Typ	Erforderlich	Beschreibung
`format`	path	string: json, xml	ja	Antwortformat

Anfragetext (application/x-www-form-urlencoded)

Name	Typ	Erforderlich	Beschreibung
`Email`	string	ja	Abzumeldende Adresse
`Comment`	string		Freier Kommentar
`ListId`	integer (int64)		Abmeldeliste des Kontos (optional)

Antworten

Code	Beschreibung
`200`	Erledigt. `AlreadyUnsubscribed` ist true, wenn die Adresse bereits abgemeldet war.
`400`	Eine gültige Adresse ist erforderlich
`401`	Ungültige Zugangsdaten
`404`	`ListId` ist keine Abmeldeliste dieses Kontos

Beispiel 200

{
  "Result": "OK",
  "AlreadyUnsubscribed": false
}

POST `/suppression/unsubscribers/{Id}/del.{format}`

Abmeldung entfernen

Source ist erforderlich, wie von /suppression/unsubscribers zurückgegeben: Eine Id allein ist nicht eindeutig.

OAuth-Scope : contacts:write

Parameter

Name	Ort	Typ	Erforderlich	Beschreibung
`format`	path	string: json, xml	ja	Antwortformat
`Id`	path	integer (int64)	ja	`Id` der Abmeldung

Anfragetext (application/x-www-form-urlencoded)

Name	Typ	Erforderlich	Beschreibung
`Source`	string	ja	`contact`, `list`, `smtp`, `api` oder `api3`

Antworten

Code	Beschreibung
`200`	Abmeldung entfernt
`400`	`Source` ist erforderlich
`401`	Ungültige Zugangsdaten
`404`	Abmeldung nicht gefunden

Beispiel 200

{
  "Result": "OK",
  "Removed": 9012
}

Code	Beschreibung
`200`	Tägliche Statistiken erfolgreich zurückgegeben
`401`	Ungültige Zugangsdaten

Code	Beschreibung
`200`	Aufschlüsselung nach Land zurückgegeben
`401`	Ungültige Zugangsdaten

Code	Beschreibung
`200`	Aufschlüsselung nach Betriebssystem zurückgegeben
`401`	Ungültige Zugangsdaten

Code	Beschreibung
`200`	Aufschlüsselung nach E-Mail-Client zurückgegeben
`401`	Ungültige Zugangsdaten

Code	Beschreibung
`200`	Neues Geheimnis (einmalig sichtbar)
`404`	Webhook nicht gefunden

Code	Beschreibung
`200`	Array von Zustellversuchen (neueste zuerst)
`404`	Webhook nicht gefunden

Code	Beschreibung
`202`	Wiederholung in die Warteschlange gestellt
`404`	Webhook oder Zustellung nicht gefunden

Mailpro™ Email API v2 : Referenz

Authentifizierung

Methode 1 — OAuth 2.0 (empfohlen für Integrationen)

Methode 2 — Bearer JWT (Legacy)

Methode 3 — IdClient + ApiKey

OAuth-Scope-Prüfung pro Endpunkt (Email v2)

Antwortformat

Paginierung

Fehlerantworten

Zustellverfolgung (transaktionale E-Mails)

Webhooks

Funktionsweise

Payload-Umschlag

Ereigniskatalog

HMAC-Signatur

Node.js

PHP

Python

C#

Wiederholungen und automatische Deaktivierung

Erfolg = HTTP 2xx

Limits

Inhalt

Authentication

POST /token

Unterstützte Grant-Typen

Token-Lebensdauer

Account

GET /account/credits.{format}

GET /account/subscriptionEndDate.{format}

GET /account/limits.{format}

Lists

GET /list/list.{format}

POST /list/add.{format}

POST /list/edit.{format}

POST /list/del.{format}

Contacts

GET /email/list.{format}

POST /email/add.{format}

POST /email/addSingle.{format}

POST /email/edit.{format}

POST /email/del.{format}

Messages

GET /message/list.{format}

POST /message/add.{format}

POST /message/edit.{format}

POST /message/del.{format}

Campaigns

GET /send/list.{format}

POST /send/campaign.{format}

POST /send/del.{format}

GET /send/scheduled.{format}

POST /send/{IdSend}/cancel.{format}

PATCH /send/{IdSend}/reschedule.{format}

POST /send/sendingTest.{format}

Transactional

GET /send/mail/scheduled.{format}

POST /send/mail/{IdSingleSend}/cancel.{format}

POST /send/mail/{IdSingleSend}/reschedule.{format}

POST /send/sendmail.{format}

GET /send/{IdSend}/status.{format}

Sender Addresses

GET /senderEmail/list.{format}

POST /senderEmail/add.{format}

POST /senderEmail/{IdSenderEmail}/resendValidation.{format}

GET /senderEmail/{IdSenderEmail}/authentication.{format}

POST /senderEmail/del.{format}

Statistics

GET /stats/list.{format}

GET /stats/byHour.{format}

GET /stats/byDay.{format}

POST /stats/del.{format}

GET /stats/country.{format}

GET /stats/open.{format}

GET /stats/click.{format}

GET /stats/system.{format}

GET /stats/emailSoftware.{format}

GET /stats/bounce.{format}

History

GET /history/list.{format}

POST `/token`

GET `/account/credits.{format}`

GET `/account/subscriptionEndDate.{format}`

GET `/account/limits.{format}`

GET `/list/list.{format}`

POST `/list/add.{format}`

POST `/list/edit.{format}`

POST `/list/del.{format}`

GET `/email/list.{format}`

POST `/email/add.{format}`

POST `/email/addSingle.{format}`

POST `/email/edit.{format}`

POST `/email/del.{format}`

GET `/message/list.{format}`

POST `/message/add.{format}`

POST `/message/edit.{format}`

POST `/message/del.{format}`

GET `/send/list.{format}`

POST `/send/campaign.{format}`

POST `/send/del.{format}`

GET `/send/scheduled.{format}`

POST `/send/{IdSend}/cancel.{format}`

PATCH `/send/{IdSend}/reschedule.{format}`

POST `/send/sendingTest.{format}`

GET `/send/mail/scheduled.{format}`

POST `/send/mail/{IdSingleSend}/cancel.{format}`

POST `/send/mail/{IdSingleSend}/reschedule.{format}`

POST `/send/sendmail.{format}`

GET `/send/{IdSend}/status.{format}`

GET `/senderEmail/list.{format}`

POST `/senderEmail/add.{format}`

POST `/senderEmail/{IdSenderEmail}/resendValidation.{format}`

GET `/senderEmail/{IdSenderEmail}/authentication.{format}`

POST `/senderEmail/del.{format}`

GET `/stats/list.{format}`

GET `/stats/byHour.{format}`

GET `/stats/byDay.{format}`

POST `/stats/del.{format}`

GET `/stats/country.{format}`

GET `/stats/open.{format}`

GET `/stats/click.{format}`

GET `/stats/system.{format}`

GET `/stats/emailSoftware.{format}`

GET `/stats/bounce.{format}`

GET `/history/list.{format}`

POST `/import/upload.{format}`

GET `/webhooks`

POST `/webhooks`

GET `/webhooks/{id}`

PUT `/webhooks/{id}`

DELETE `/webhooks/{id}`

POST `/webhooks/{id}/test`

POST `/webhooks/{id}/rotate-secret`

GET `/webhooks/{id}/deliveries`

POST `/webhooks/{id}/deliveries/{deliveryId}/replay`

GET `/suppression/bounces.{format}`

POST `/suppression/bounces/{Id}/del.{format}`

POST `/suppression/bounces/{Id}/restore.{format}`

GET `/suppression/unsubscribers.{format}`

POST `/suppression/unsubscribers/add.{format}`

POST `/suppression/unsubscribers/{Id}/del.{format}`