Mailpro™ SMS API : Referenz

POST /token

Access-Token abrufen (307-Weiterleitung an /v3/token)

Bezieht einen Bearer-JWT-Token mit Mailpro-Client-Anmeldedaten. Übergeben Sie den zurückgegebenen access_token als Authorization: Bearer <token> in allen nachfolgenden Anfragen. Derselbe Token ist auch für die CRM API v3 und die Email v2 API gültig.

> ⚙ Implementierungsdetail — POST /sms/token ist eine 307 Temporary > Redirect an POST /v3/token (konfiguriert in der IIS-web.config- > Rewrite-Schicht). HTTP 307 bewahrt sowohl die Methode (POST) als > auch den Anfrage-Body, sodass jeder standardkonforme HTTP-Client > der Weiterleitung transparent folgt — Sie senden weiterhin Anfragen an > /sms/token und erhalten ein gültiges JWT zurück. Es gibt keine duplizierte > Token-Ausstellungslogik; die SMS API stellt selbst nie Tokens aus.

Unterstützte Grant-Typen

Token-Lebensdauer

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

Verwenden Sie grant_type=refresh_token, um den 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. Vollständige Sicherheitshinweise finden Sie in der CRM API v3 /token-Dokumentation.

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/limits.{format}

Monatliches API-Kontingent abrufen

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

Kontingentberechnung: Das Limit wird aus den E-Mail- Abonnement-Credits kalibriert (typischerweise subscription_credits × 5). Für einen 10.000-E-Mails/Monat-Plan ergibt dies ein monatliches Budget von 50.000 Anfragen. Zurückgesetzt am Jahrestag des Abonnements (nicht am

• des Kalendermonats).

Was Credits verbraucht:

• Jede authentifizierte API-Anfrage an v2-, v3- oder sms-Endpoints.
• Jedes Webhook-Ereignis, das an einen abonnierten Endpoint gesendet wird.

Was KOSTENLOS ist (verbraucht keine Credits):

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

Das Kontingent wird über alle 3 Mailpro-APIs hinweg geteilt (v2, v3, sms) — ein Client = ein monatliches Budget für die gesamte Plattform. SMS- Versand verbraucht zusätzlich das dedizierte SMS-Credit-Guthaben (GET /credit/get.{format}).

OAuth-Scope : account:read

Parameter

Antworten

Beispiel 200

{
  "monthlyLimit": 50000,
  "remaining": 32847,
  "used": 17153,
  "isFree": false,
  "remainedSendsForFree": null
}

POST /send/add.{format}

Massen-SMS an eine Kontaktliste senden

Sendet eine SMS-Nachricht an alle Telefonnummern in einer Kontaktliste. Unterstützt Terminierung: Setzen Sie scheduled_time auf ein zukünftiges Datum, um später zu senden, oder lassen Sie es weg, um sofort zu senden.

Credit-Verbrauch: Credits werden zum Versandzeitpunkt abgezogen. Lange Nachrichten (>160 GSM-7-Zeichen) werden in mehrere Teile aufgeteilt, von denen jeder zusätzliche Credits kostet.

Die Antwort gibt { "Error": "Insufficient Credit", "Code": 202 } zurück, wenn das Konto über unzureichende Credits verfügt.

OAuth-Scope : sms:send

Parameter

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

Antworten

Beispiel 200

{
  "Id": 6001,
  "Message": "Flash sale today only — 30% off all orders. Shop now at mailpro.com/shop",
  "ScheduledTime": "2026-04-20T10:00:00",
  "To": [
    "42"
  ]
}

Beispiel 202

{
  "Error": "Insufficient Credit",
  "Code": 202
}

Beispiel 400

{
  "Error": "Malformed Input",
  "Code": 103
}

GET /send/add_single.{format}

Eine einzelne SMS senden (GET)

Sendet eine einzelne SMS an einen Empfänger über eine GET-Anfrage. Nützlich für einfache Integrationen, bei denen POST nicht verfügbar ist. Anmeldedaten und Nachricht werden als Query-Parameter übergeben.

Hinweis: Vermeiden Sie GET für sensible Nachrichten — Query-Parameter erscheinen in den Server-Logs. Bevorzugen Sie stattdessen POST /send/add_single.

OAuth-Scope : sms:send

Parameter

Antworten

Beispiel 200

{
  "Id": 5001,
  "Message": "Your appointment is confirmed for tomorrow at 10:00.",
  "ScheduledTime": "2026-04-15T09:00:00",
  "To": "0041791234567",
  "Charge": "1"
}

POST /send/add_single.{format}

Eine einzelne SMS senden

Sendet eine einzelne SMS-Nachricht an eine Empfänger-Telefonnummer. Unterstützt Terminierung über scheduled_time.

Credit-Verbrauch: Credits werden zum Versandzeitpunkt abgezogen. Das Feld Charge in der Antwort zeigt, wie viele Credits verbraucht wurden.

Die Antwort gibt { "Error": "Insufficient Credit", "Code": 202 } zurück, wenn das Konto über unzureichende Credits verfügt.

OAuth-Scope : sms:send

Parameter

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

Antworten

Beispiel 200

{
  "Id": 5001,
  "Message": "Your verification code is 8472. Valid for 10 minutes.",
  "ScheduledTime": "2026-04-15T14:30:00",
  "To": "0041791234567",
  "Charge": "1"
}

Beispiel 202

{
  "Error": "Insufficient Credit",
  "Code": 202
}

Beispiel 400

{
  "Error": "Malformed Input",
  "Code": 103
}

GET /send/list.{format}

SMS-Kampagnen auflisten

Gibt die Liste der SMS-Kampagnen (Massenversände) für das Konto zurück. Paginierung über die Header NumberOfRecords und PageNumber.

Verwenden Sie type_to, um nach Versandtyp zu filtern:

• 0 (Standard) — Massenversände an Listen
• 1 — einzelne Einzelversände

OAuth-Scope : sms:send

Parameter

Antworten

Beispiel 200

[
  {
    "Id": 5001,
    "Message": "Your verification code is 8472",
    "ScheduledTime": "2026-04-15T09:00:00",
    "To": "41791234567"
  }
]

POST /send/del.{format}

Einen SMS-Versand stornieren oder löschen

Storniert einen anstehenden terminierten SMS-Versand oder löscht einen abgeschlossenen aus der Historie. Nur in der Zukunft terminierte Versände können storniert werden. Laufende Versände können nicht gestoppt werden.

OAuth-Scope : sms:send

Parameter

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

Antworten

Beispiel 200

{
  "Result": "OK"
}

Beispiel 500

{
  "Error": "Delete failed",
  "Code": 500
}

GET /send/scheduled.{format}

Meine terminierten SMS-Versände auflisten

Gibt die SMS-Versände (Einzel oder Kampagne) zurück, die für ein zukünftiges Datum terminiert sind und noch nicht versendet wurden. Nützlich vor dem Aufruf von /cancel oder /reschedule.

Datensätze sind aufsteigend nach scheduled_time sortiert.

OAuth-Scope : sms:send

Parameter

Antworten

Beispiel 200

[
  {
    "Id": 9001,
    "Message": "Black Friday: 30% off until midnight.",
    "ScheduledTime": "2026-11-27T12:00:00",
    "To": "+33671234567"
  }
]

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

Einen terminierten SMS-Versand stornieren

Storniert eine terminierte SMS, die noch nicht versendet wurde. Wenn der Versand bereits verarbeitet wurde (oder nicht existiert / einem anderen Client gehört), wird 409 Conflict zurückgegeben.

OAuth-Scope : sms:send

Parameter

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

Antworten

Beispiel 200

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

Beispiel 409

{
  "error": "conflict",
  "message": "Send not found, not owned by client, or already dispatched."
}

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

Einen terminierten SMS-Versand umterminieren

Aktualisiert das geplante Datum einer terminierten SMS, die noch nicht versendet wurde. Das neue Datum muss in der Zukunft und innerhalb von 90 Tagen liegen.

Name des Datumsfelds: Die API akzeptiert scheduled_time (primär) sowie die Legacy-Aliase PlanDate, date_planned und DatePlanned. Geben Sie eines davon an — das erste Nicht-Null-Feld wird verwendet.

OAuth-Scope : sms:send

Parameter

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

Antworten

Beispiel 200

{
  "Result": "OK",
  "Id": 9001,
  "NewScheduledTime": "2026-12-31T14:30:00"
}

Beispiel 409

{
  "error": "conflict",
  "message": "Reschedule failed — send not found, already dispatched, or new date out of range."
}

GET /list/list.{format}

Telefon-Kontaktlisten auflisten

Gibt alle SMS-Kontaktlisten für das Konto zurück. Verwenden Sie die zurückgegebenen Id-Werte beim Versenden von Massen-SMS-Kampagnen oder beim Hinzufügen von Telefonnummern.

OAuth-Scope : sms:contacts:read

Parameter

Antworten

Beispiel 200

{
  "Items": [
    {
      "AddressBookId": 42,
      "Name": "Newsletter subscribers",
      "TotalNumberPhones": 1547
    },
    {
      "AddressBookId": 43,
      "Name": "Loyalty program",
      "TotalNumberPhones": 823
    }
  ]
}

POST /list/add.{format}

Eine Kontaktliste erstellen

Erstellt eine neue SMS-Kontaktliste mit dem angegebenen Namen. Die Liste beginnt leer — fügen Sie Telefonnummern mit POST /phone/add 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.

Parameter

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

Antworten

Beispiel 200

{
  "Id": 44,
  "Name": "Spring campaign 2026",
  "NumberPhones": 0
}

Beispiel 400

{
  "Error": "Malformed Input",
  "Code": 103
}

POST /list/edit.{format}

Eine Kontaktliste umbenennen

Aktualisiert den Anzeigenamen einer bestehenden SMS-Kontaktliste. Die Telefonnummern in der Liste bleiben davon unberührt.

OAuth-Scope : sms:contacts:write

Parameter

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

Antworten

POST /list/del.{format}

Eine Kontaktliste löschen

Löscht eine SMS-Kontaktliste und alle darin enthaltenen Telefonnummern dauerhaft. Diese Aktion kann nicht rückgängig gemacht werden.

OAuth-Scope : sms:contacts:write

Parameter

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

Antworten

GET /phone/list.{format}

Telefonnummern in einer Kontaktliste auflisten

Gibt eine paginierte Liste der Telefonnummern in einer bestimmten Kontaktliste zurück. Verwenden Sie address_book_id, um anzugeben, welche Liste abgerufen werden soll. Paginierung: NumberOfRecords und PageNumber (standardmäßig 5.000 pro Seite, Seite 1).

OAuth-Scope : sms:contacts:read

Parameter

Antworten

Beispiel 200

{
  "Items": [
    {
      "Id": 1001,
      "Number": "41791234567",
      "FirstName": "Alice",
      "LastName": "Dupont"
    },
    {
      "Id": 1002,
      "Number": "33612345678",
      "FirstName": "Bob",
      "LastName": "Martin"
    }
  ]
}

POST /phone/add.{format}

Telefonnummer(n) zu einer Liste hinzufügen

Fügt einer Kontaktliste eine oder mehrere Telefonnummern hinzu.

Einzelne Nummer: verwenden Sie das Feld number.

Massenimport: verwenden Sie das Feld phone_list mit durch Semikola getrennten Nummern: +41791234567;+33612345678;0049301234567

Telefonnummern akzeptieren +, 00 oder das reine Format — siehe Phone number format in der API-Beschreibung für die vollständige Liste der akzeptierten / abgelehnten Eingaben. Doppelte Nummern werden stillschweigend übersprungen, sofern nicht force=1 gesetzt ist.

OAuth-Scope : sms:contacts:write

Parameter

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

Antworten

Beispiel 200

{
  "Id": 1003,
  "Number": "0041791234567",
  "FirstName": "Alice",
  "LastName": "Dupont"
}

POST /phone/edit.{format}

Telefonnummerneintrag aktualisieren

Aktualisiert die Telefonnummer und/oder die Kontaktdaten eines bestehenden Eintrags. Verwenden Sie number_id (aus /phone/list), um den zu aktualisierenden Eintrag zu identifizieren. Nur die in der Anfrage angegebenen Felder werden aktualisiert.

OAuth-Scope : sms:contacts:write

Parameter

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

Antworten

POST /phone/del.{format}

Eine Telefonnummer aus einer Liste entfernen

Entfernt einen bestimmten Telefonnummerneintrag dauerhaft aus seiner Kontaktliste. Verwenden Sie number_id (aus /phone/list), um den Eintrag zu identifizieren.

OAuth-Scope : sms:contacts:write

Parameter

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

Antworten

GET /credit/get.{format}

SMS-Credit-Guthaben abrufen

Gibt das aktuelle SMS-Credit-Guthaben für Ihr Konto zurück. SMS-Credits werden zum Versandzeitpunkt verbraucht. Eine Standard-SMS (≤160 GSM-7-Zeichen) kostet 1 Credit. Längere Nachrichten oder Nachrichten mit Sonderzeichen können mehr kosten.

> Hinweis: Dies gibt Ihr SMS-Versand-Credit-Guthaben zurück, nicht Ihr API-Anfragekontingent. > Für das API-Kontingent siehe GET /account/limits.{format}.

OAuth-Scope : sms:read

Parameter

Antworten

Beispiel 200

{
  "TotalCredits": 5000
}

GET /history/list.{format}

SMS-Versandhistorie auflisten

Gibt ein paginiertes Protokoll aller von diesem Konto versendeten SMS-Kampagnen zurück. Die Ergebnisse sind absteigend nach Datum sortiert (neueste zuerst). Paginierung: NumberOfRecords und PageNumber (Header oder Query, standardmäßig 5.000 pro Seite).

OAuth-Scope : sms:read

Parameter

Antworten

Beispiel 200

{
  "Items": [
    {
      "Id": 583294,
      "DateSent": "2026-07-17T18:56:39.813",
      "Message": "Your verification code is 8472",
      "Charge": 3,
      "Parts": 1
    }
  ]
}

POST /import/upload.{format}

Datei mit Telefonnummern (CSV / XLSX) für den Massenimport hochladen

Laden Sie eine CSV- oder XLSX-Datei hoch, um Telefonnummern in eine Kontaktliste zu importieren. Die Datei wird gespeichert und für die asynchrone Verarbeitung in die Warteschlange gestellt — der Endpoint gibt sofort eine ImportJobId zurück.

Anfragetyp: multipart/form-data

Erforderliche Formularfelder:

• id_client (Ganzzahl) — Ihre Mailpro-Client-ID
• api_key (Zeichenkette) — Ihr API-Schlüssel
• id_list (Ganzzahl) — ID der Ziel-Kontaktliste
• file (binär) — die hochzuladende CSV- oder XLSX-Datei

Optional:

• webhook_url (Zeichenkette) — HTTPS-URL, die nach Abschluss der Verarbeitung aufgerufen wird. Empfängt einen JSON-Payload mit dem Endstatus (success / failed) und der Anzahl importierter / übersprungener / ungültiger Zeilen.

Dateiformat:

• UTF-8-kodiert
• Erste Zeile = Überschriften (eine davon muss Phone oder PhoneNumber sein — Groß-/Kleinschreibung wird ignoriert)
• Nummern im internationalen Format (E.164), z. B. +41791234567
• Maximale Dateigröße: 50 MB

OAuth-Scope : sms:contacts:write

Parameter

Anfragetext (multipart/form-data)

Antworten

Beispiel 200

{
  "Result": "OK",
  "ImportJobId": 15,
  "InternalName": "230575-20260420142616-phones.csv"
}

GET /webhooks

Webhooks auflisten

Gibt jeden auf dem authentifizierten Konto konfigurierten Webhook zurück.

Antworten

Beispiel 200

{
  "items": [
    {
      "id": 14,
      "url": "https://example.com/hooks/mailpro",
      "description": "Slack-Integration",
      "is_active": true,
      "created_at": "2026-07-01T21:09:52.43",
      "updated_at": "2026-07-21T18:56:08.02",
      "last_delivery_at": "2026-07-21T18:56:07.653",
      "last_delivery_status": 200,
      "consecutive_failures": 0,
      "events": [
        "sms.delivered",
        "sms.failed"
      ]
    }
  ],
  "total": 1
}

POST /webhooks

Einen 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, um die HMAC-Signatur jedes eingehenden Payloads zu verifizieren.

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

Anfragetext (application/json)

Beispiel

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

Antworten

Beispiel 201

{
  "id": 42,
  "url": "https://example.com/hooks/mailpro",
  "events": [
    "sms.delivered",
    "sms.failed"
  ],
  "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 /webhooks/{id}

Einen Webhook abrufen

Parameter

Antworten

PUT /webhooks/{id}

Einen Webhook aktualisieren

Teilaktualisierung — nur die gesendeten Felder werden geändert.

Parameter

Anfragetext (application/json)

Antworten

DELETE /webhooks/{id}

Einen Webhook löschen

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

Parameter

Antworten

POST /webhooks/{id}/test

Ein Testereignis senden

Stellt ein sofortiges ping-Ereignis (oder einen anderen Ereignistyp über das eventType-Body-Feld) für Ihren Endpoint in die Warteschlange. Nützlich, um Erreichbarkeit und Signaturverifizierung zu überprüfen, bevor Sie sich auf echte Ereignisse verlassen.

Parameter

Anfragetext (application/json)

Beispiel

{
  "eventType": "ping"
}

Antworten

Beispiel 202

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

POST /webhooks/{id}/rotate-secret

HMAC-Geheimnis rotieren

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

Verwenden Sie dies, wenn Sie vermuten, dass Ihr Geheimnis kompromittiert wurde.

Parameter

Antworten

Beispiel 200

{
  "secret": "whsec_XyzA9876BcdE5432FghI1098JklM7654NopQ"
}

GET /webhooks/{id}/deliveries

Zustellversuche auflisten

Gibt die Historie der Zustellversuche für diesen Webhook zurück (30 Tage Aufbewahrung). Nützlich zum Debugging — welche Ereignisse wurden gesendet, welche Statuscodes wurden empfangen, Anzahl der Wiederholungen, Fehlermeldungen.

Parameter

Antworten

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

Eine Zustellung erneut abspielen

Stellt einen neuen Zustellversuch mit demselben Payload wie dem Original in die Warteschlange. Nützlich, um eine fehlgeschlagene Zustellung erneut auszulösen, nachdem Sie Ihren Endpoint repariert haben. Eine NEUE Webhook_Delivery-Zeile wird erstellt (das Original wird zu Auditzwecken aufbewahrt). Der Replay durchläuft die Standard-Retry-Richtlinie (gleicher Backoff-Zeitplan, gleiche Auto-Deaktivierungsregel nach 10 Fehlschlägen).

Parameter

Antworten