Mailpro™ SMS API : Reference

POST /token

Get access token (307 redirect to /v3/token)

Obtains a Bearer JWT token using Mailpro client credentials. Pass the returned access_token as Authorization: Bearer <token> in all subsequent requests. The same token is also valid on the CRM API v3 and the Email v2 API.

> ⚙ Implementation detail — POST /sms/token is a 307 Temporary > Redirect to POST /v3/token (configured at the IIS web.config > rewrite layer). HTTP 307 preserves both the method (POST) and > the request body, so any standards-compliant HTTP client follows > the redirect transparently — you keep posting to /sms/token and get > a valid JWT back. There is no duplicated token-issuance logic; the > SMS API never issues tokens itself.

Supported grant types

Token lifetime

• Access token: 30 days
• Refresh token: 90 days

Use grant_type=refresh_token to renew the access token without re-authenticating. Store tokens server-side (Vault, env vars); never embed in browser JS or mobile app binaries. See the CRM API v3 /token doc for the full security note.

Request body (application/x-www-form-urlencoded)

Responses

Example 200

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

Example 400

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

GET /account/limits.{format}

Get monthly API quota

Returns the monthly API request quota for the authenticated client.

Quota calculation: the limit is calibrated from the email subscription credits (typically subscription_credits × 5). For a 10,000-email/month plan, this yields a 50,000-request monthly budget. Reset on the subscription anniversary date (not the 1st of the calendar month).

What consumes credits:

• Every authenticated API request to v2, v3 or sms endpoints.
• Every webhook event dispatched to a subscribed endpoint.

What is FREE (does not consume credits):

• /health endpoints.
• Requests that fail with 401, 403 or 429.
• Webhook events for clients with no matching subscription.

The quota is shared across all 3 Mailpro APIs (v2, v3, sms) — one client = one monthly budget across the whole platform. SMS sends additionally consume the dedicated SMS credit balance (GET /credit/get.{format}).

OAuth scope : account:read

Parameters

Responses

Example 200

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

POST /send/add.{format}

Send bulk SMS to a contact list

Sends an SMS message to all phone numbers in a contact list. Supports scheduling: set scheduled_time to a future date to send later, or omit it to send immediately.

Credit consumption: credits are deducted at send time. Long messages (>160 GSM-7 chars) are split into multiple parts, each costing additional credits.

The response returns { "Error": "Insufficient Credit", "Code": 202 } if the account has insufficient credits.

OAuth scope : sms:send

Parameters

Request body (application/x-www-form-urlencoded)

Responses

Example 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"
  ]
}

Example 202

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

Example 400

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

GET /send/add_single.{format}

Send a single SMS (GET)

Sends a single SMS to one recipient via a GET request. Useful for simple integrations where POST is not available. Credentials and message are passed as query parameters.

Note: avoid using GET for sensitive messages — query parameters appear in server logs. Prefer POST /send/add_single instead.

OAuth scope : sms:send

Parameters

Responses

Example 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}

Send a single SMS

Sends a single SMS message to one recipient phone number. Supports scheduling via scheduled_time.

Credit consumption: credits are deducted at send time. The Charge field in the response shows how many credits were consumed.

The response returns { "Error": "Insufficient Credit", "Code": 202 } if the account has insufficient credits.

OAuth scope : sms:send

Parameters

Request body (application/x-www-form-urlencoded)

Responses

Example 200

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

Example 202

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

Example 400

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

GET /send/list.{format}

List SMS campaigns

Returns the list of SMS campaigns (bulk sends) for the account. Pagination via NumberOfRecords and PageNumber headers.

Use type_to to filter by send type:

• 0 (default) — address-book bulk sends
• 1 — single individual sends

OAuth scope : sms:send

Parameters

Responses

Example 200

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

POST /send/del.{format}

Cancel or delete an SMS send

Cancels a pending scheduled SMS send, or deletes a completed one from history. Only future-scheduled sends can be cancelled. Sends in progress cannot be stopped.

OAuth scope : sms:send

Parameters

Request body (application/x-www-form-urlencoded)

Responses

Example 200

{
  "Result": "OK"
}

Example 500

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

GET /send/scheduled.{format}

List my scheduled SMS sends

Returns the SMS sends (single or campaign) scheduled for a future date that have not yet been dispatched. Useful before calling /cancel or /reschedule.

Records are sorted by scheduled_time ascending.

OAuth scope : sms:send

Parameters

Responses

Example 200

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

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

Cancel a scheduled SMS send

Cancels a scheduled SMS that has not yet been dispatched. If the send has already been processed (or doesn't exist / belongs to another client), returns 409 Conflict.

OAuth scope : sms:send

Parameters

Request body (application/x-www-form-urlencoded)

Responses

Example 200

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

Example 409

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

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

Reschedule a scheduled SMS send

Updates the planned date of a scheduled SMS that has not yet been dispatched. New date must be in the future and within 90 days.

Date field name: the API accepts scheduled_time (primary) as well as the legacy aliases PlanDate, date_planned, and DatePlanned. Provide any one of them — the first non-null is used.

OAuth scope : sms:send

Parameters

Request body (application/x-www-form-urlencoded)

Responses

Example 200

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

Example 409

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

GET /list/list.{format}

List phone contact lists

Returns all SMS contact lists for the account. Use the returned Id values when sending bulk SMS campaigns or adding phone numbers.

OAuth scope : sms:contacts:read

Parameters

Responses

Example 200

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

POST /list/add.{format}

Create a contact list

Creates a new SMS contact list with the given name. The list starts empty — add phone numbers with POST /phone/add. Maximum 1,000 lists per account (same limit on the three Mailpro APIs and in the app). Returns HTTP 422 if the limit is reached.

Parameters

Request body (application/x-www-form-urlencoded)

Responses

Example 200

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

Example 400

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

POST /list/edit.{format}

Rename a contact list

Updates the display name of an existing SMS contact list. The phone numbers in the list are not affected.

OAuth scope : sms:contacts:write

Parameters

Request body (application/x-www-form-urlencoded)

Responses

POST /list/del.{format}

Delete a contact list

Permanently deletes an SMS contact list and all the phone numbers it contains. This action cannot be undone.

OAuth scope : sms:contacts:write

Parameters

Request body (application/x-www-form-urlencoded)

Responses

GET /phone/list.{format}

List phone numbers in a contact list

Returns a paginated list of phone numbers in a specific contact list. Use address_book_id to specify which list to retrieve. Pagination: NumberOfRecords and PageNumber (5,000 per page by default, page 1).

OAuth scope : sms:contacts:read

Parameters

Responses

Example 200

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

POST /phone/add.{format}

Add phone number(s) to a list

Adds one or more phone numbers to a contact list.

Single number: use the number field.

Bulk import: use the phone_list field with numbers separated by semicolons: +41791234567;+33612345678;0049301234567

Phone numbers accept +, 00 or bare format — see Phone number format in the API description for the full list of accepted / rejected inputs. Duplicate numbers are silently skipped unless force=1 is set.

OAuth scope : sms:contacts:write

Parameters

Request body (application/x-www-form-urlencoded)

Responses

Example 200

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

POST /phone/edit.{format}

Update a phone number entry

Updates the phone number and/or contact details of an existing entry. Use number_id (from /phone/list) to identify the entry to update. Only fields provided in the request are updated.

OAuth scope : sms:contacts:write

Parameters

Request body (application/x-www-form-urlencoded)

Responses

POST /phone/del.{format}

Remove a phone number from a list

Permanently removes a specific phone number entry from its contact list. Use number_id (from /phone/list) to identify the entry.

OAuth scope : sms:contacts:write

Parameters

Request body (application/x-www-form-urlencoded)

Responses

GET /credit/get.{format}

Get SMS credit balance

Returns the current SMS credit balance for your account. SMS credits are consumed at send time. One standard SMS (≤160 GSM-7 characters) costs 1 credit. Longer messages or messages with special characters may cost more.

> Note: this returns your SMS send credit balance, not your API request quota. > For the API quota see GET /account/limits.{format}.

OAuth scope : sms:read

Parameters

Responses

Example 200

{
  "TotalCredits": 5000
}

GET /history/list.{format}

List SMS sending history

Returns a paginated log of all past SMS campaigns sent from this account. Results are ordered by date descending (most recent first). Pagination: NumberOfRecords and PageNumber (headers or query, 5,000 per page by default).

OAuth scope : sms:read

Parameters

Responses

Example 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}

Upload a phone-numbers file (CSV / XLSX) for bulk import

Upload a CSV or XLSX file to import phone numbers into a contact list. The file is stored and queued for asynchronous processing — the endpoint returns an ImportJobId immediately.

Request type: multipart/form-data

Required form fields:

• id_client (integer) — your Mailpro client ID
• api_key (string) — your API key
• id_list (integer) — target contact list ID
• file (binary) — the CSV or XLSX file to upload

Optional:

• webhook_url (string) — HTTPS URL called when processing finishes. Receives a JSON payload with the final status (success / failed) and counts of imported / skipped / invalid rows.

File format:

• UTF-8 encoded
• First row = headers (one must be Phone or PhoneNumber — case-insensitive)
• Numbers in international format (E.164), e.g. +41791234567
• Max file size: 50 MB

OAuth scope : sms:contacts:write

Parameters

Request body (multipart/form-data)

Responses

Example 200

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

GET /webhooks

List webhooks

Returns every webhook configured on the authenticated account.

Responses

Example 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

Create a webhook

Creates a new webhook subscription. The response contains a secret that is shown only once — store it immediately, server-side. Use it to verify the HMAC signature of every incoming payload.

Limits: max 20 webhooks per account, max 50 events per webhook.

Request body (application/json)

Example

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

Responses

Example 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}

Get a webhook

Parameters

Responses

PUT /webhooks/{id}

Update a webhook

Partial update — only the sent fields are modified.

Parameters

Request body (application/json)

Responses

DELETE /webhooks/{id}

Delete a webhook

Permanently deletes the webhook and its full delivery history.

Parameters

Responses

POST /webhooks/{id}/test

Send a test event

Queues an immediate ping event (or any other event type via the eventType body field) to your endpoint. Useful to verify reachability and signature verification before relying on real events.

Parameters

Request body (application/json)

Example

{
  "eventType": "ping"
}

Responses

Example 202

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

POST /webhooks/{id}/rotate-secret

Rotate the HMAC secret

Generates a new HMAC secret and invalidates the old one immediately. The new secret is returned once in the response — store it. Every delivery from this point on will be signed with the new secret.

Use this if you suspect your secret has been compromised.

Parameters

Responses

Example 200

{
  "secret": "whsec_XyzA9876BcdE5432FghI1098JklM7654NopQ"
}

GET /webhooks/{id}/deliveries

List delivery attempts

Returns the history of dispatch attempts for this webhook (30-day retention). Useful for debugging — which events were sent, status codes received, retry counts, error messages.

Parameters

Responses

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

Replay a delivery

Queues a fresh delivery attempt with the same payload as the original. Useful to re-trigger a failed delivery after fixing your endpoint. A NEW Webhook_Delivery row is created (the original is preserved for audit). The replay goes through the standard retry policy (same backoff schedule, same 10-failure auto-disable rule).

Parameters

Responses