Mailpro™ CRM API v3 : Referenz

POST /token

Access-Token abrufen

Bezieht ein Bearer-JWT-Token mithilfe von Client-Anmeldedaten. Übergeben Sie das zurückgegebene access_token als Authorization: Bearer <token> in allen nachfolgenden Anfragen.

Unterstützte Grant-Typen

Token-Gültigkeitsdauer

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

Verwenden Sie grant_type=refresh_token, um ein frisches Access-Token ohne erneute Authentifizierung zu erhalten — Ihr SDK sollte dies automatisch tun, wenn das Access-Token kurz vor dem Ablauf steht (typische Strategie: Erneuerung, wenn weniger als 24 h verbleiben).

Tokens sicher speichern

Auch bei einer Gültigkeitsdauer von 30 Tagen kann jede Person, die in den Besitz eines access_token kommt, Ihr Konto bis zu dessen Ablauf imitieren. Speichern Sie Tokens in einem serverseitigen Secret-Store (Vault, AWS Secrets Manager, Azure Key Vault, Umgebungs- variablen auf einem gehärteten Host). Niemals ein Token einbetten in:

• clientseitiges JavaScript oder ein beliebiges Browser-Bundle
• mobile Apps, die an Endbenutzer ausgeliefert werden (die Binärdatei kann inspiziert werden)
• öffentliche Git-Repositorys oder CI-Build-Logs

Wenn ein Token offengelegt wurde, widerrufen Sie es über die Einstellungen Ihres Mailpro-Kontos und fordern Sie ein neues an.

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

Antworten

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."
}

GET /Account/Me

Kontodetails abrufen

Gibt die Profildetails und Einstellungen des authentifizierten Mailpro-Kontos zurück.

Antworten

GET /Account/Credits

Guthabenstand abrufen

Gibt das verbleibende E-Mail- und SMS-Guthaben des Kontos zurück.

Antworten

Beispiel 200

{
  "email_credits": 48500,
  "sms_credits": 1200
}

GET /Account/SubscriptionEndDate

Abonnement-Enddatum abrufen

Gibt das Ablaufdatum des aktuellen Mailpro-Abonnements zurück.

Antworten

GET /Account/Limits

Monatliches API-Kontingent abrufen

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

Kontingentberechnung: Das Limit wird aus den E-Mail- Abonnementguthaben kalibriert (typischerweise subscription_credits × 5). Für einen Tarif mit 10.000 E-Mails/Monat ergibt dies ein monatliches Budget von 50.000 Anfragen. Die exakte Zuordnung wird vom Abrechnungsjob bei der Abonnementregistrierung festgelegt und am Jahrestag des Abonnements zurückgesetzt (nicht am

• des Kalendermonats).

Was Guthaben verbraucht:

• Jede authentifizierte API-Anfrage an die Endpunkte v2, v3 oder sms (jeder Aufruf = 1 Guthaben, unabhängig vom Ergebnis — sowohl 2xx als auch die meisten fachlichen 4xx-Fehler zählen).
• Jedes Webhook-Ereignis, das an einen abonnierten Endpunkt zugestellt wird (z. B. contact.created, das an Ihren abonnierten Webhook ausgelöst wird = 1 Guthaben zusätzlich zum auslösenden API-Aufruf).

Was KOSTENLOS ist (verbraucht kein Guthaben):

• /health-Endpunkte (Monitoring).
• Anfragen, die mit 401 (Authentifizierungsfehler), 403 (verboten) oder 429 (Rate-Limit überschritten) fehlschlagen.
• Webhook-Ereignisse für Clients ohne passendes Abonnement (zwischengespeicherter Kurzschluss — keine Auswirkung auf das Kontingent).

Antworten

POST /Contact

Kontakt erstellen

Erstellt einen neuen CRM-Kontakt mit optionalen benutzerdefinierten Feldern, Listenzuweisungen und Tags.

Erforderlich:

• email — muss kontoübergreifend eindeutig sein
• lists — mindestens eine Listenzuweisung ist verpflichtend

Telefonnummern akzeptieren +41…, 0041… oder 41… mit oder ohne Trennzeichen (maximal 12 Ziffern für Kontakte — siehe Telefonnummernformat in der API-Beschreibung).

Benutzerdefinierte Felder werden über ihre id identifiziert (aus GET /Field). Die Werte werden gegen den Typ des Felds validiert.

OAuth-Scope : contacts:write

Anfragetext (application/json)

Beispiel

{
  "email": "[email protected]",
  "phone_number": "+41791234567",
  "lists": [
    {
      "id": 101
    }
  ],
  "tags": [
    {
      "id": 5
    }
  ],
  "custom_fields": [
    {
      "id": 1,
      "value": "Alice"
    },
    {
      "id": 2,
      "value": "Dupont"
    }
  ]
}

Antworten

Beispiel 406

{
  "Message": "Contact cannot be created. A contact already exist with the same Email"
}

POST /Contact/Multiple

Kontakte importieren (Massenvorgang)

Erstellt bis zu 1.000 Kontakte in einer einzigen Anfrage für einen effizienten Massenimport. Die Antwort enthält eine Liste der erfolgreich erstellten Kontakte sowie eine Fehlerliste für Kontakte, die nicht erstellt werden konnten (z. B. doppelte E-Mail-Adresse, ungültige Daten).

Hinweis: In Massenimporten verwendete Listen und Tags dürfen nicht mit aktiven Automatisierungs-Workflows verknüpft sein. Andernfalls wird der gesamte Import mit HTTP 406 abgelehnt.

OAuth-Scope : contacts:write

Anfragetext (application/json)

Beispiel

[
  {
    "email": "[email protected]",
    "lists": [
      {
        "id": 101
      }
    ],
    "custom_fields": [
      {
        "id": 1,
        "value": "Alice"
      }
    ]
  },
  {
    "email": "[email protected]",
    "lists": [
      {
        "id": 101
      }
    ],
    "custom_fields": [
      {
        "id": 1,
        "value": "Bob"
      }
    ]
  }
]

Antworten

Beispiel 200

{
  "Added": [
    {
      "Email": "[email protected]",
      "Id": "550e8400-e29b-41d4-a716-446655440000"
    },
    {
      "Email": "[email protected]",
      "Id": "660e8400-e29b-41d4-a716-446655440001"
    }
  ],
  "Errors": []
}

GET /Contact/{id}

Kontakt abrufen

Gibt die Details eines bestimmten Kontakts zurück. Verwenden Sie includeTags=true, um auch die dem Kontakt zugewiesenen Tags zurückzugeben. Verwenden Sie includeLists=true, um auch die Listen zurückzugeben, denen der Kontakt angehört.

OAuth-Scope : contacts:read

Parameter

Antworten

Beispiel 200

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "email": "[email protected]",
  "phone_number": "41791234567",
  "custom_fields": [
    {
      "id": 1,
      "value": "Alice"
    },
    {
      "id": 2,
      "value": "Dupont"
    }
  ],
  "tags": [
    {
      "id": 5
    }
  ],
  "lists": [
    {
      "id": 101
    }
  ]
}

PUT /Contact/{id}

Kontakt aktualisieren

Aktualisiert die E-Mail-Adresse, Telefonnummer, benutzerdefinierten Felder, Listenzuweisungen und Tags eines Kontakts. Der Anfrage-Body ersetzt die aktuellen Daten des Kontakts — geben Sie alle Listen und Tags an, denen der Kontakt weiterhin zugewiesen bleiben soll.

Im Body erforderlich: email und mindestens ein lists-Eintrag.

OAuth-Scope : contacts:write

Parameter

Anfragetext (application/json)

Antworten

Beispiel 200

{
  "Result": "Successful operation"
}

DELETE /Contact/{id}

Kontakt löschen

Löscht einen Kontakt dauerhaft aus dem CRM.

OAuth-Scope : contacts:write

Parameter

Antworten

GET /Contact/{id}/Activity

Aktivität eines Kontakts über 90 Tage

Empfangene, geöffnete und angeklickte E-Mails, bevorzugtes E-Mail-Programm und letzte Kampagnen des Kontakts.

OAuth-Scope : contacts:read

Parameter

Antworten

Beispiel 200

{
  "period_days": 90,
  "email_received": 12,
  "email_opened": 7,
  "email_clicked": 2,
  "favorite_email_client": "Gmail",
  "last_campaigns": [
    {
      "id": 5001,
      "name": "Spring Sale 2026",
      "date": "2026-10-01T09:00:00"
    }
  ]
}

PUT /Contact/{id}/Tag/{tagid}

Tag zu Kontakt hinzufügen

Weist einem Kontakt ein Tag zu. Ist das Tag bereits zugewiesen, ist der Vorgang ein No-Op.

OAuth-Scope : contacts:write

Parameter

Antworten

DELETE /Contact/{id}/Tag/{tagid}

Tag von Kontakt entfernen

Entfernt eine Tag-Zuweisung von einem Kontakt.

OAuth-Scope : contacts:write

Parameter

Antworten

PUT /Contact/{id}/List/{listid}

Kontakt zu Liste hinzufügen

Fügt einen Kontakt einer bestimmten Liste hinzu. Gibt HTTP 404 zurück, wenn der Kontakt zuvor von dieser Liste abgemeldet wurde.

OAuth-Scope : contacts:write

Parameter

Antworten

DELETE /Contact/{id}/List/{listid}

Kontakt aus Liste entfernen

Entfernt einen Kontakt aus einer bestimmten Liste. Der Kontakt selbst wird nicht gelöscht.

OAuth-Scope : contacts:write

Parameter

Antworten

GET /List

Kontaktlisten auflisten

Gibt alle Kontaktlisten des Kontos zurück. Filterung nach Name oder Erstellungsdatum. Alphabetische Sortierung mit sortByName=true. Mit includeTotalContacts=true wird die Gesamtzahl der Kontakte pro Liste mit einbezogen.

OAuth-Scope : contacts:read

Parameter

Antworten

Beispiel 200

[
  {
    "id": 101,
    "name": "Newsletter subscribers",
    "total_contacts": 4521,
    "date_creation": "2025-01-15T10:30:00"
  }
]

POST /List

Kontaktliste erstellen

Erstellt eine neue Kontaktliste. Maximal 1.000 Listen pro Konto.

OAuth-Scope : contacts:write

Anfragetext (application/json)

Beispiel

{
  "name": "Spring Campaign 2026"
}

Antworten

Beispiel 200

{
  "id": 102,
  "name": "Spring Campaign 2026",
  "date_creation": "2026-04-14T12:00:00"
}

GET /List/{id}

Kontaktliste abrufen

Gibt die Details einer bestimmten Kontaktliste zurück.

OAuth-Scope : contacts:read

Parameter

Antworten

PUT /List/{id}

Kontaktliste aktualisieren

Benennt eine bestehende Kontaktliste um.

OAuth-Scope : contacts:write

Parameter

Anfragetext (application/json)

Beispiel

{
  "name": "Newsletter subscribers — Europe"
}

Antworten

DELETE /List/{id}

Kontaktliste löschen

Löscht eine Kontaktliste dauerhaft. Die Kontakte selbst werden nicht gelöscht — nur ihre Zugehörigkeit zu dieser Liste wird entfernt. Listen, die von aktiven Automatisierungs-Workflows verwendet werden, können nicht gelöscht werden.

OAuth-Scope : contacts:write

Parameter

Antworten

GET /List/{id}/Contact

Kontakte in einer Liste auflisten

Gibt die Kontakte zurück, die einer bestimmten Liste angehören. Filterung nach E-Mail oder Hinzufügedatum. Tags und Listenzugehörigkeiten mit den entsprechenden Flags einbeziehen.

OAuth-Scope : contacts:read

Parameter

Antworten

GET /List/{listId}/Unsubscribers

Abgemeldete auflisten

Gibt die Kontakte zurück, die sich von einer bestimmten Liste abgemeldet haben.

OAuth-Scope : contacts:read

Parameter

Antworten

GET /Tag

Tags auflisten

Gibt alle Tags des Kontos zurück.

OAuth-Scope : contacts:read

Parameter

Antworten

Beispiel 200

[
  {
    "id": 5,
    "name": "VIP customers"
  },
  {
    "id": 6,
    "name": "Newsletter openers"
  }
]

POST /Tag

Tag erstellen

Erstellt ein neues Tag. Maximal 1.000 Tags pro Konto.

OAuth-Scope : contacts:write

Anfragetext (application/json)

Beispiel

{
  "name": "VIP customers"
}

Antworten

GET /Tag/{id}

Tag abrufen

Gibt ein bestimmtes Tag anhand seiner ID zurück.

OAuth-Scope : contacts:read

Parameter

Antworten

PUT /Tag/{id}

Tag aktualisieren

Benennt ein bestehendes Tag um.

OAuth-Scope : contacts:write

Parameter

Anfragetext (application/json)

Beispiel

{
  "name": "VIP customers — updated"
}

Antworten

DELETE /Tag/{id}

Tag löschen

Löscht ein Tag dauerhaft. Das Tag wird von allen Kontakten entfernt. Tags, die von aktiven Automatisierungs-Workflows verwendet werden, können nicht gelöscht werden.

OAuth-Scope : contacts:write

Parameter

Antworten

GET /Tag/{id}/Contact

Kontakte mit einem Tag auflisten

Gibt die Kontakte zurück, denen ein bestimmtes Tag zugewiesen wurde.

OAuth-Scope : contacts:read

Parameter

Antworten

GET /Field

Benutzerdefinierte Felder auflisten

Gibt alle für das Konto definierten benutzerdefinierten Kontaktfelder zurück. Verwenden Sie die zurückgegebenen id-Werte beim Erstellen oder Aktualisieren von Kontakten.

Parameter

Antworten

Beispiel 200

[
  {
    "id": 1,
    "name": "first_name",
    "personalisation_key": "first_name",
    "field_type": "text"
  },
  {
    "id": 2,
    "name": "last_name",
    "personalisation_key": "last_name",
    "field_type": "text"
  }
]

POST /Field

Benutzerdefiniertes Feld erstellen

Erstellt ein neues benutzerdefiniertes Kontaktfeld. Maximal 50 Felder pro Konto. Verwenden Sie die zurückgegebene id, um Kontakten Werte zuzuweisen.

Anfragetext (application/json)

Beispiel

{
  "name": "First name",
  "id_field_type": 1,
  "personalize_key": "first_name"
}

Antworten

GET /Field/Types

Feldtypen auflisten

Gibt die verfügbaren Feldtyp-Kennungen zurück, die beim Erstellen eines benutzerdefinierten Felds zu verwenden sind. Gängige Typen: 1 = Text, 2 = Zahl, 3 = Datum.

Antworten

GET /Field/{id}

Benutzerdefiniertes Feld abrufen

Gibt die Definition und Metadaten eines bestimmten benutzerdefinierten Felds zurück.

Parameter

Antworten

PUT /Field/{id}

Benutzerdefiniertes Feld aktualisieren

Aktualisiert den Namen oder den Personalisierungsschlüssel eines benutzerdefinierten Felds.

Parameter

Anfragetext (application/json)

Antworten

DELETE /Field/{id}

Benutzerdefiniertes Feld löschen

Löscht ein benutzerdefiniertes Feld dauerhaft und entfernt dessen Wert aus allen Kontakten. Diese Aktion kann nicht rückgängig gemacht werden.

Parameter

Antworten

GET /Campaign

Kampagnen auflisten

Gibt eine paginierte Liste der E-Mail-Kampagnen des Kontos zurück.

Parameter

Antworten

Beispiel 200

[
  {
    "id": 8001,
    "title": "Spring Newsletter April 2026",
    "date_planned": "2026-04-20T09:00:01",
    "count_open": 1823,
    "count_sent": 4521,
    "count_click": 342,
    "count_badmail": 12,
    "count_unsubscription": 8,
    "count_clicking_users": 289,
    "count_complaints": 1,
    "spam_trap": 0,
    "deliverability_score": 98
  }
]

GET /Campaign/{id}

Kampagne abrufen

Gibt die Konfiguration und die Statistikzusammenfassung einer bestimmten Kampagne zurück.

Parameter

Antworten

PUT /Campaign/{id}

Kampagne aktualisieren

Aktualisiert den Titel oder das Sendedatum einer geplanten Kampagne. Kampagnen können nur bis 5 Minuten vor dem geplanten Sendezeitpunkt geändert werden.

Parameter

Anfragetext (application/json)

Antworten

DELETE /Campaign/{id}

Kampagne löschen

Storniert und löscht eine Kampagne anhand ihrer Kennung dauerhaft.

Parameter

Antworten

GET /Campaign/Scheduled

Meine geplanten Kampagnen auflisten

Gibt Kampagnen mit zukünftigem date_planned zurück, die noch nicht versendet wurden. Sortiert nach date_planned in aufsteigender Reihenfolge.

Parameter

Antworten

Beispiel 200

[
  {
    "id": 5001,
    "id_client": 12345,
    "subject": "Spring Sale 2026",
    "date_planned": "2026-05-01T09:00:00",
    "title": "Spring Sale",
    "id_campaign": 7001,
    "id_list": 101,
    "id_segment": null,
    "number_email": 1250
  }
]

POST /Campaign/{id}/Cancel

Geplante Kampagne stornieren

Storniert eine zukünftig geplante Kampagne. Gibt 409 Conflict zurück, wenn die Kampagne bereits versendet wurde oder nicht existiert.

Parameter

Antworten

Beispiel 200

{
  "result": "ok",
  "cancelled": 5001
}

PATCH /Campaign/{id}/Reschedule

Geplante Kampagne neu planen

Aktualisiert das geplante Sendedatum einer geplanten Kampagne. Das neue Datum muss in der Zukunft und innerhalb von 90 Tagen liegen.

Name des Body-Felds: Die API akzeptiert date_planned (snake_case, primär) sowie die Legacy-Aliasse PlanDate und scheduled_time. Geben Sie einen beliebigen davon an — der erste nicht-null-Wert wird verwendet.

Parameter

Anfragetext (application/json)

Antworten

Beispiel 200

{
  "result": "ok",
  "id": 5001,
  "date_planned": "2026-12-31T14:30:00"
}

GET /Campaign/{id}/ByHour

Statistik nach Stunde

Gibt die stündliche Aufschlüsselung der Öffnungen und Klicks für die Kampagne zurück.

Parameter

Antworten

GET /Campaign/{id}/ByDay

Statistik nach Tag

Gibt die tägliche Aufschlüsselung der Öffnungen und Klicks für die Kampagne zurück.

Parameter

Antworten

GET /Campaign/{id}/Openings

E-Mail-Öffnungen auflisten

Gibt eine paginierte Liste der Kontakte zurück, die die Kampagnen-E-Mail geöffnet haben.

Parameter

Antworten

GET /Campaign/{id}/Clicks

Link-Klicks auflisten

Gibt eine paginierte Liste der Kontakte zurück, die in der Kampagne auf einen Link geklickt haben.

Parameter

Antworten

GET /Campaign/{id}/HardBounces

Hard Bounces auflisten

Gibt die E-Mail-Adressen zurück, bei denen während dieser Kampagne ein Hard Bounce aufgetreten ist.

Parameter

Antworten

GET /Campaign/{id}/Links

Verfolgte Links auflisten

Gibt die Klick-Leistungsdaten für jeden in der Kampagne verfolgten Link zurück.

Parameter

Antworten

GET /Campaign/{id}/OS

Statistik nach Betriebssystem / Gerät

Gibt die Aufschlüsselung der Öffnungen und Klicks nach Betriebssystem und Gerätetyp zurück.

Parameter

Antworten

GET /Campaign/{id}/EmailClients

Statistik nach E-Mail-Client

Gibt die Aufschlüsselung der Öffnungen nach E-Mail-Client zurück (Gmail, Outlook, Apple Mail…).

Parameter

Antworten

GET /Campaign/{id}/Countries

Statistik nach Land

Gibt die geografische Verteilung der Öffnungen und Klicks zurück.

Parameter

Antworten

POST /Send/Mail

Transaktionale E-Mail senden

Sendet eine einmalige transaktionale E-Mail an einen einzelnen Empfänger.

Empfänger: Geben Sie email (inline angegebene Adresse) ODER id_contact (CRM-Kontakt) an — nicht beides. Die Verwendung von id_contact ermöglicht die automatische Personalisierung mit den Werten der benutzerdefinierten Felder des Kontakts.

Inhalt: Geben Sie body_html (inline angegebenes HTML) ODER id_message (gespeicherte Vorlage) an — nicht beides. Wenn beide angegeben werden, hat id_message Vorrang.

Erforderlich: id_sender_email, subject und eines von (email oder id_contact) sowie eines von (body_html oder id_message).

Anfragetext (application/json)

Beispiel

{
  "id_sender_email": 201,
  "email": "[email protected]",
  "subject": "Your order #12345 has shipped",
  "body_html": "<p>Hello {{first_name}}, your order is on its way!</p>",
  "reply_to": "[email protected]",
  "fields": [
    {
      "id": 1,
      "value": "Alice"
    }
  ],
  "attachments": [
    {
      "filename": "invoice.pdf",
      "content": "JVBERi0xLjQKJVBERi0xLjQK..."
    }
  ]
}

Antworten

Beispiel 200

{
  "message": "Successful operation",
  "id_single_send": 8001
}

Beispiel 404

{
  "Message": "Not enough credit available"
}

GET /Send/{id}/Status

Zustellstatus einer transaktionalen E-Mail abrufen

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

Mögliche Werte: delivered (vom Empfängerserver angenommen, siehe diag_code), bounced (abgelehnt — bounce_type: 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, date_planned 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.

Parameter

Antworten

Beispiel 200

{
  "id_single_send": 8001,
  "email": "[email protected]",
  "status": "delivered",
  "date_planned": "2026-04-15T14:30:00",
  "status_date": "2026-04-15T14:30:07",
  "diag_code": "2.0.0 (success)",
  "bounce_type": null
}

POST /Send/Campaign

E-Mail-Kampagne senden

Sendet eine E-Mail-Massenkampagne an eine oder mehrere Kontaktlisten.

Erforderlich:

• id_message — die zu sendende Vorlage (aus GET /Message)
• id_sender_email — die Absenderadresse (aus GET /SenderEmail)
• lists — mindestens eine Ziel-Kontaktliste
• campaign_title — Bezeichnung zur Statistik-Nachverfolgung

Segment: Optional können Empfänger nach einem gespeicherten Segment gefiltert werden (id_segment). Das Segment filtert die Kontakte innerhalb der angegebenen Listen.

Planung: Setzen Sie date_planned auf ein zukünftiges ISO-8601-Datum/-Uhrzeit. Kampagnen können bis 5 Minuten vor dem geplanten Zeitpunkt bearbeitet oder storniert werden.

Anfragetext (application/json)

Beispiel

{
  "id_message": 501,
  "id_sender_email": 201,
  "lists": [
    {
      "id": 101
    }
  ],
  "campaign_title": "Spring Newsletter April 2026",
  "date_planned": "2026-04-20T09:00:00"
}

Antworten

Beispiel 200

{
  "Message": "Successful operation. Campaigns can be edited or deleted until 5 minutes prior to send.",
  "IdCampaign": 8001
}

GET /Send

Geplante Sendungen auflisten

Gibt die Liste der E-Mail-Kampagnen zurück, die auf ihren Versand warten (geplant, noch nicht verarbeitet).

Parameter

Antworten

DELETE /Send/{id}

Geplante Sendung stornieren

Storniert und löscht eine geplante E-Mail-Sendung, die noch nicht verarbeitet wurde. Sendungen, die gerade verarbeitet werden, können nicht storniert werden.

Parameter

Antworten

GET /Send/Mail/Scheduled

Geplante Einzel-E-Mails auflisten

Gibt die mit POST /Send/Mail und einem zukünftigen Datum gesendeten Einzel-E-Mails zurück, die noch nicht versendet wurden. Kampagnen werden von GET /Campaign/Scheduled aufgelistet.

OAuth-Scope : email:send

Antworten

Beispiel 200

[
  {
    "id_single_send": 880123,
    "email": "[email protected]",
    "subject": "Your invoice",
    "date_planned": "2026-12-01T09:00:00"
  }
]

POST /Send/Mail/{id}/Cancel

Geplante Einzel-E-Mail stornieren

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

OAuth-Scope : email:send

Parameter

Antworten

Beispiel 200

{
  "result": "ok",
  "cancelled": 880123
}

PATCH /Send/Mail/{id}/Reschedule

Geplante Einzel-E-Mail neu planen

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

OAuth-Scope : email:send

Parameter

Anfragetext (application/json)

Antworten

Beispiel 200

{
  "result": "ok",
  "id": 880123,
  "date_planned": "2026-12-15T09:00:00"
}

GET /SenderEmail

Absenderadressen auflisten

Gibt die für das Konto konfigurierten validierten Absender-E-Mail-Adressen zurück.

Parameter

Antworten

Beispiel 200

[
  {
    "id": 201,
    "email": "[email protected]",
    "sender_name": "Your Company Newsletter",
    "is_validated": true
  }
]

POST /SenderEmail

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

Anfragetext (application/json)

Antworten

Beispiel 200

{
  "result": "ok",
  "confirmation_sent": true,
  "domain_has_mx": true
}

POST /SenderEmail/{id}/ResendValidation

Bestätigungs-E-Mail erneut senden

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

OAuth-Scope : email:templates:write

Parameter

Antworten

Beispiel 200

{
  "result": "ok",
  "confirmation_sent": true
}

GET /SenderEmail/{id}/Authentication

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: dkim_settings_url öffnet die richtige Seite.

OAuth-Scope : email:templates:read

Parameter

Antworten

Beispiel 200

{
  "domain": "example.com",
  "spf": {
    "valid": true,
    "record": "v=spf1 include:spf.mailpro.com -all",
    "recommended_record": "v=spf1 include:spf.mailpro.com -all",
    "change_needed": 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"
  },
  "dkim_settings_url": "https://app.mailpro.com/dkim/list?d=example.com"
}

GET /History/Email

Verlauf der E-Mail-Versendungen auflisten

Gibt das Protokoll vergangener E-Mail-Versendungen des Kontos zurück.

Parameter

Antworten

GET /History/SMS

Verlauf der SMS-Versendungen auflisten

Gibt das Protokoll vergangener SMS-Versendungen des Kontos zurück.

Parameter

Antworten

GET /Segment

Segmente auflisten

Gibt alle für das Konto gespeicherten dynamischen Segmente zurück.

OAuth-Scope : contacts:read

Parameter

Antworten

GET /Segment/{id}/Contact

Kontakte eines Segments auflisten

Mit id_list werden nur die Kontakte dieser Liste im Segment zurückgegeben: diejenigen, die eine Kampagne Liste + Segment erreichen würde. Die Gesamtzahl steht im Header X-Total-Count.

OAuth-Scope : contacts:read

Parameter

Antworten

GET /Segment/{id}/Count

Kontakte eines Segments zählen

Nur die Anzahl, um die Größe eines Versands im Voraus zu kennen. Mit id_list werden nur die Kontakte dieser Liste im Segment gezählt.

OAuth-Scope : contacts:read

Parameter

Antworten

Beispiel 200

{
  "total": 1250
}

GET /Segment/{id}/contact/{contactId}/check

Prüfen, ob ein Kontakt einem Segment entspricht

Prüft, ob ein bestimmter Kontakt (per GUID) aktuell den Regeln eines bestimmten Segments entspricht. Nützlich, um Automatisierungslogik bei Bedarf auszulösen.

OAuth-Scope : contacts:read

Parameter

Antworten

POST /Sms/SingleSMS

Einzel-SMS senden

Sendet eine einzelne SMS direkt an eine Telefonnummer. Verwenden Sie dies für transaktionale Nachrichten (OTPs, Bestellbestätigungen, Benachrichtigungen). Die Telefonnummer akzeptiert +41…, 0041… oder 41… mit oder ohne Trennzeichen — siehe Telefonnummernformat in der API-Beschreibung für akzeptierte / abgelehnte Eingaben.

Anfragetext (application/json)

Beispiel

{
  "phone_number": "+41791234567",
  "message": "Your verification code is 9473. Valid for 10 minutes."
}

Antworten

POST /Sms/Campaign

SMS-Kampagne senden

Sendet eine SMS-Nachricht an das Feld phone_number aller Kontakte in einer oder mehreren Listen. Kontakte ohne Telefonnummer werden übersprungen.

Anfragetext (application/json)

Beispiel

{
  "lists": [
    {
      "id": 101
    }
  ],
  "message": "Flash sale today — 20% off. Shop at mailpro.com",
  "date_planned": "2026-04-20T10:00:00"
}

Antworten

GET /Sms

SMS-Verlauf auflisten

Gibt das Protokoll der SMS-Versendungen (sowohl Einzel- als auch Kampagnen-SMS) des Kontos zurück.

Parameter

Antworten

DELETE /Sms/{id}

Geplante SMS stornieren

Storniert eine ausstehende geplante SMS-Sendung.

Parameter

Antworten

GET /Sms/Scheduled

Geplante SMS-Sendungen auflisten

Gibt SMS-Sendungen mit zukünftigem date_planned (noch nicht versendet) zurück, aufsteigend nach Datum sortiert.

Parameter

Antworten

POST /Sms/{id}/Cancel

Geplante SMS stornieren

Storniert eine geplante SMS-Sendung nur, wenn diese noch nicht versendet wurde.

Parameter

Antworten

PATCH /Sms/{id}/Reschedule

Geplante SMS neu planen

Aktualisiert das geplante Sendedatum einer geplanten SMS. Das neue Datum muss in der Zukunft und innerhalb von 90 Tagen liegen. Schlägt fehl, wenn die SMS bereits versendet wurde.

Name des Body-Felds: Die API akzeptiert date_planned (snake_case, primär) sowie die Legacy-Aliasse PlanDate und scheduled_time. Geben Sie einen beliebigen davon an.

Parameter

Anfragetext (application/json)

Antworten

GET /FolderList

Listenordner auflisten

Gibt die zur Organisation von Kontaktlisten verwendeten Ordner zurück.

Parameter

Antworten

GET /FolderList/{id}

Einzelnen Listenordner abrufen

Gibt die Details eines Listenordners anhand seiner ID zurück.

Parameter

Antworten

GET /FolderMessage

Nachrichtenordner auflisten

Gibt die zur Organisation von E-Mail-Nachrichtenvorlagen verwendeten Ordner zurück.

Parameter

Antworten

POST /Import/Upload

Kontaktdatei (CSV / XLSX) für Massenimport hochladen

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

Anfragetyp: multipart/form-data

Erforderliche Formularfelder:

• id_list (Ganzzahl) — ID der Zielliste
• file (Binär) — die hochzuladende CSV- oder XLSX-Datei
• json_match_fields (Zeichenfolge, JSON) — welche Spalte der Datei in welches Kontaktfeld geht. email_position = Spalte der E-Mail-Adresse, ab 0 gezählt (erforderlich), phone_position = Spalte der Mobilnummer oder -1, fields = IDs der übrigen Felder (siehe GET /Field), fields_position = Spalte jedes dieser Felder, update_fields = bestehende Kontakte aktualisieren. Fehlende oder ungültige Zuordnung: Antwort 400, es wird kein Import angelegt.

Optional:

• webhook_url (Zeichenfolge) — HTTPS-URL, die beim Abschluss der Verarbeitung aufgerufen wird. Empfängt einen JSON-Payload mit dem endgültigen Status (success / failed) und der Anzahl der importierten / übersprungenen / ungültigen Zeilen.

Dateiformat:

• UTF-8-kodiert
• Die erste Zeile darf Kopfzeilen enthalten (automatische Erkennung: eine erste Zeile ohne E-Mail-Adresse wird übersprungen)
• Die Spalten werden über json_match_fields den Feldern zugeordnet
• Maximale Dateigröße: 50 MB

Anfragetext (multipart/form-data)

Antworten

Beispiel 200

{
  "result": "OK",
  "import_job_id": 14,
  "internal_name": "230575-20260420142615-contacts.csv"
}

GET /Webhook

Webhooks auflisten

Gibt alle für das authentifizierte Konto konfigurierten Webhooks zurück.

Antworten

POST /Webhook

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 jedes eingehenden Payloads.

Limits: maximal 20 Webhooks pro Konto, maximal 50 Ereignisse pro Webhook.

Anfragetext (application/json)

Beispiel

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

Antworten

Beispiel 201

{
  "id": 42,
  "url": "https://example.com/hooks/mailpro",
  "events": [
    "email.delivered",
    "email.bounced",
    "contact.created"
  ],
  "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"
}

GET /Webhook/{id}

Webhook abrufen

Parameter

Antworten

PUT /Webhook/{id}

Webhook aktualisieren

Teilaktualisierung — nur die gesendeten Felder werden geändert.

Parameter

Anfragetext (application/json)

Antworten

DELETE /Webhook/{id}

Webhook löschen

Löscht den Webhook und seine vollständige Zustellungshistorie dauerhaft.

Parameter

Antworten

POST /Webhook/{id}/test

Testereignis senden

Reiht sofort ein ping-Ereignis (oder einen beliebigen anderen Ereignistyp über das Body-Feld eventType) für Ihren Endpunkt in die Warteschlange ein. Nützlich, um die Erreichbarkeit und die Signaturprüfung zu verifizieren, bevor Sie sich auf reale Ereignisse verlassen.

Parameter

Anfragetext (application/json)

Beispiel

{
  "eventType": "ping"
}

Antworten

Beispiel 202

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

POST /Webhook/{id}/rotate-secret

HMAC-Secret rotieren

Erstellt ein neues HMAC-Secret und macht das alte sofort ungültig. Das neue Secret wird einmalig in der Antwort zurückgegeben — speichern Sie es. Jede Zustellung ab diesem Zeitpunkt wird mit dem neuen Secret signiert.

Verwenden Sie diese Funktion, wenn Sie den Verdacht haben, dass Ihr Secret kompromittiert wurde.

Parameter

Antworten

Beispiel 200

{
  "secret": "whsec_XyzA9876BcdE5432FghI1098JklM7654NopQ"
}

GET /Webhook/{id}/deliveries

Zustellversuche auflisten

Gibt die Historie der Zustellversuche für diesen Webhook zurück (30 Tage Aufbewahrung). Nützlich zur Fehlersuche — welche Ereignisse wurden gesendet, welche Statuscodes wurden empfangen, wie viele Wiederholungsversuche und welche Fehlermeldungen.

Parameter

Antworten

POST /Webhook/{id}/deliveries/{deliveryId}/replay

Zustellung wiederholen

Reiht einen frischen Zustellversuch mit demselben Payload wie das Original in die Warteschlange ein. Nützlich, um eine fehlgeschlagene Zustellung nach Behebung Ihres Endpunkts erneut auszulösen. Eine NEUE Webhook_Delivery-Zeile wird angelegt (das Original bleibt zu Prüfzwecken erhalten). Die Wiederholung durchläuft die standardmäßige Wiederholungsrichtlinie (10s → 1min → 5min → 30min → 2h → 6h → 24h, dann aufgegeben).

Parameter

Antworten

GET /Suppression/Bounces

Bounces des Kontos auflisten

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

OAuth-Scope : email:read

Parameter

Antworten

Beispiel 200

[
  {
    "id": 5521,
    "source": "contact",
    "type": "hard",
    "email": "[email protected]",
    "date": "2026-10-12T08:30:00",
    "diag_code": "550 5.1.1 User unknown",
    "id_list": 101
  }
]

DELETE /Suppression/Bounces/{id}

Bounce entfernen

source und type sind erforderlich, wie von GET /Suppression/Bounces zurückgegeben: Eine id allein ist nicht eindeutig.

OAuth-Scope : contacts:write

Parameter

Antworten

Beispiel 200

{
  "result": "ok",
  "id": 5521,
  "restored": false
}

POST /Suppression/Bounces/{id}/Restore

Kontakt mit Hard Bounce wieder in seine Listen aufnehmen

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

OAuth-Scope : contacts:write

Parameter

Antworten

Beispiel 200

{
  "result": "ok",
  "id": 5521,
  "restored": true
}

GET /Suppression/Unsubscribers

Abmeldungen des Kontos auflisten

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

OAuth-Scope : contacts:read

Parameter

Antworten

Beispiel 200

[
  {
    "id": 9012,
    "source": "api3",
    "email": "[email protected]",
    "date": "2026-10-20T16:05:00",
    "list_name": null,
    "comment": "Asked by phone"
  }
]

POST /Suppression/Unsubscribers

Abmeldung hinzufügen

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

OAuth-Scope : contacts:write

Anfragetext (application/json)

Antworten

Beispiel 200

{
  "result": "ok",
  "already_unsubscribed": false
}

DELETE /Suppression/Unsubscribers/{id}

Abmeldung entfernen

source ist erforderlich, wie von GET /Suppression/Unsubscribers zurückgegeben: Eine id allein ist nicht eindeutig.

OAuth-Scope : contacts:write

Parameter

Antworten

Beispiel 200

{
  "result": "ok",
  "removed": 9012
}