Mailpro™ CRM API v3 : Reference

POST /token

Get access token

Obtains a Bearer JWT token using client credentials. Pass the returned access_token as Authorization: Bearer <token> in all subsequent requests.

Supported grant types

Token lifetime

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

Use grant_type=refresh_token to obtain a fresh access token without re-authenticating — your SDK should do this automatically when the access token gets close to expiry (typical strategy: refresh when less than 24 h remaining).

Storing tokens securely

Even with a 30-day lifetime, anyone who obtains an access_token can impersonate your account until it expires. Store tokens in a server-side secret store (Vault, AWS Secrets Manager, Azure Key Vault, environment variables on a hardened host). Never embed a token in:

• client-side JavaScript or any browser bundle
• mobile apps shipped to end users (the binary can be inspected)
• public Git repositories or CI build logs

If a token is leaked, revoke it via your Mailpro account settings and request a new one.

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/Me

Get account details

Returns the profile details and settings of the authenticated Mailpro account.

Responses

GET /Account/Credits

Get credit balance

Returns the remaining email and SMS credit balance for the account.

Responses

Example 200

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

GET /Account/SubscriptionEndDate

Get subscription end date

Returns the expiry date of the current Mailpro subscription.

Responses

GET /Account/Limits

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. The exact mapping is set by the billing job at subscription signup and 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 (each call = 1 credit, regardless of the result — 2xx and most 4xx business errors both count).
• Every webhook event dispatched to a subscribed endpoint (e.g. contact.created fired to your subscribed webhook = 1 credit on top of the API call that triggered it).

What is FREE (does not consume credits):

• /health endpoints (monitoring).
• Requests that fail with 401 (auth fail), 403 (forbidden) or 429 (rate-limited).
• Webhook events for clients with no matching subscription (cached short-circuit — no quota impact).

Responses

POST /Contact

Create a contact

Creates a new CRM contact with optional custom fields, list assignments, and tags.

Required:

• email — must be unique across the account
• lists — at least one list assignment is mandatory

Phone numbers accept +41…, 0041… or 41… with or without separators (max 12 digits on Contact — see Phone number format in the API description).

Custom fields are identified by their id (from GET /Field). Values are validated against the field's type.

OAuth scope : contacts:write

Request body (application/json)

Example

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

Responses

Example 406

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

POST /Contact/Multiple

Import contacts (bulk)

Creates up to 1,000 contacts in a single request for efficient bulk import. The response includes a list of successfully created contacts and a list of errors for contacts that could not be created (e.g. duplicate email, invalid data).

Note: lists and tags used in bulk imports must not be linked to active automation workflows. If they are, the entire import is rejected with HTTP 406.

OAuth scope : contacts:write

Request body (application/json)

Example

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

Responses

Example 200

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

GET /Contact/{id}

Get a contact

Returns the details of a specific contact. Use includeTags=true to also return the tags assigned to the contact. Use includeLists=true to also return the lists the contact belongs to.

OAuth scope : contacts:read

Parameters

Responses

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

Update a contact

Updates a contact's email, phone number, custom fields, list assignments, and tags. The request body replaces the contact's current data — include all lists and tags you want the contact to remain assigned to.

Required in body: email and at least one lists entry.

OAuth scope : contacts:write

Parameters

Request body (application/json)

Responses

Example 200

{
  "Result": "Successful operation"
}

DELETE /Contact/{id}

Delete a contact

Permanently deletes a contact from the CRM.

OAuth scope : contacts:write

Parameters

Responses

GET /Contact/{id}/Activity

Activity of a contact over 90 days

Emails received, opened and clicked, favorite email client and latest campaigns of the contact.

OAuth scope : contacts:read

Parameters

Responses

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

Add tag to contact

Assigns a tag to a contact. If the tag is already assigned, the operation is a no-op.

OAuth scope : contacts:write

Parameters

Responses

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

Remove tag from contact

Removes a tag assignment from a contact.

OAuth scope : contacts:write

Parameters

Responses

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

Add contact to list

Adds a contact to a specific list. Returns HTTP 404 if the contact was previously unsubscribed from this list.

OAuth scope : contacts:write

Parameters

Responses

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

Remove contact from list

Removes a contact from a specific list. The contact itself is not deleted.

OAuth scope : contacts:write

Parameters

Responses

GET /List

List contact lists

Returns all contact lists for the account. Filter by name or creation date. Sort alphabetically with sortByName=true. Include the total contact count per list with includeTotalContacts=true.

OAuth scope : contacts:read

Parameters

Responses

Example 200

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

POST /List

Create a contact list

Creates a new contact list. Maximum 1,000 lists per account.

OAuth scope : contacts:write

Request body (application/json)

Example

{
  "name": "Spring Campaign 2026"
}

Responses

Example 200

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

GET /List/{id}

Get a contact list

Returns the details of a specific contact list.

OAuth scope : contacts:read

Parameters

Responses

PUT /List/{id}

Update a contact list

Renames an existing contact list.

OAuth scope : contacts:write

Parameters

Request body (application/json)

Example

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

Responses

DELETE /List/{id}

Delete a contact list

Permanently deletes a contact list. The contacts themselves are not deleted — only their membership in this list is removed. Lists used by active automation workflows cannot be deleted.

OAuth scope : contacts:write

Parameters

Responses

GET /List/{id}/Contact

List contacts in a list

Returns the contacts belonging to a specific list. Filter by email or date added. Include tags and list memberships with the corresponding flags.

OAuth scope : contacts:read

Parameters

Responses

GET /List/{listId}/Unsubscribers

List unsubscribers

Returns the contacts who have unsubscribed from a specific list.

OAuth scope : contacts:read

Parameters

Responses

GET /Tag

List tags

Returns all tags for the account.

OAuth scope : contacts:read

Parameters

Responses

Example 200

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

POST /Tag

Create a tag

Creates a new tag. Maximum 1,000 tags per account.

OAuth scope : contacts:write

Request body (application/json)

Example

{
  "name": "VIP customers"
}

Responses

GET /Tag/{id}

Get a tag

Returns a specific tag by its ID.

OAuth scope : contacts:read

Parameters

Responses

PUT /Tag/{id}

Update a tag

Renames an existing tag.

OAuth scope : contacts:write

Parameters

Request body (application/json)

Example

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

Responses

DELETE /Tag/{id}

Delete a tag

Permanently deletes a tag. The tag is removed from all contacts. Tags used by active automation workflows cannot be deleted.

OAuth scope : contacts:write

Parameters

Responses

GET /Tag/{id}/Contact

List contacts with a tag

Returns the contacts that have been assigned a specific tag.

OAuth scope : contacts:read

Parameters

Responses

GET /Field

List custom fields

Returns all custom contact fields defined for the account. Use the returned id values when creating or updating contacts.

Parameters

Responses

Example 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

Create a custom field

Creates a new custom contact field. Maximum 50 fields per account. Use the returned id when assigning values to contacts.

Request body (application/json)

Example

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

Responses

GET /Field/Types

List field types

Returns the available field type identifiers to use when creating a custom field. Common types: 1 = text, 2 = number, 3 = date.

Responses

GET /Field/{id}

Get a custom field

Returns the definition and metadata of a specific custom field.

Parameters

Responses

PUT /Field/{id}

Update a custom field

Updates the name or personalisation key of a custom field.

Parameters

Request body (application/json)

Responses

DELETE /Field/{id}

Delete a custom field

Permanently deletes a custom field and removes its value from all contacts. This action cannot be undone.

Parameters

Responses

GET /Campaign

List campaigns

Returns a paginated list of email campaigns with their performance metrics: sent, opens, clicks, unique clickers, bounces (count_badmail), unsubscribes, complaints, spam-trap hits and the deliverability score.

Parameters

Responses

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

Get a campaign

Returns the configuration and statistics summary of a specific campaign.

Parameters

Responses

PUT /Campaign/{id}

Update a campaign

Updates a scheduled campaign's title or send date. Campaigns can only be modified until 5 minutes before the scheduled send time.

Parameters

Request body (application/json)

Responses

DELETE /Campaign/{id}

Delete a campaign

Cancels and permanently deletes a campaign by its identifier.

Parameters

Responses

GET /Campaign/Scheduled

List my scheduled campaigns

Returns campaigns with date_planned in the future that have not yet been dispatched. Sorted by date_planned ascending.

Parameters

Responses

Example 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

Cancel a scheduled campaign

Cancels a campaign scheduled in the future. Returns 409 Conflict if the campaign has already been dispatched or doesn't exist.

Parameters

Responses

Example 200

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

PATCH /Campaign/{id}/Reschedule

Reschedule a scheduled campaign

Updates the planned send date of a scheduled campaign. The new date must be in the future and within 90 days.

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

Parameters

Request body (application/json)

Responses

Example 200

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

GET /Campaign/{id}/ByHour

Statistics by hour

Returns the hourly open and click breakdown for the campaign.

Parameters

Responses

GET /Campaign/{id}/ByDay

Statistics by day

Returns the daily open and click breakdown for the campaign.

Parameters

Responses

GET /Campaign/{id}/Openings

List email opens

Returns a paginated list of contacts who opened the campaign email.

Parameters

Responses

GET /Campaign/{id}/Clicks

List link clicks

Returns a paginated list of contacts who clicked a link in the campaign.

Parameters

Responses

GET /Campaign/{id}/HardBounces

List hard bounces

Returns the email addresses that hard-bounced during this campaign.

Parameters

Responses

GET /Campaign/{id}/Links

List tracked links

Returns click performance data for each tracked link in the campaign.

Parameters

Responses

GET /Campaign/{id}/OS

Statistics by OS / device

Returns the open and click breakdown by operating system and device type.

Parameters

Responses

GET /Campaign/{id}/EmailClients

Statistics by email client

Returns the open breakdown by email client (Gmail, Outlook, Apple Mail…).

Parameters

Responses

GET /Campaign/{id}/Countries

Statistics by country

Returns the geographic distribution of opens and clicks.

Parameters

Responses

POST /Send/Mail

Send transactional email

Sends a one-off transactional email to a single recipient.

Recipient: provide email (inline address) OR id_contact (CRM contact) — not both. Using id_contact enables automatic personalization with the contact's custom field values.

Content: provide body_html (inline HTML) OR id_message (saved template) — not both. If both are provided, id_message takes precedence.

Required: id_sender_email, subject, and one of (email or id_contact), and one of (body_html or id_message).

Request body (application/json)

Example

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

Responses

Example 200

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

Example 404

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

GET /Send/{id}/Status

Get delivery status of a transactional email

Returns the current delivery status of a transactional email sent with POST /Send/Mail. Pass the id_single_send that call returned.

Possible values: delivered (accepted by the recipient server, see diag_code), bounced (rejected — bounce_type: hard invalid address or permanent refusal, soft refused after retries), sent (handed to the mail server, no answer yet), scheduled (not sent yet, date_planned in the future) and queued (waiting to be dispatched). delivered and bounced are final: stop polling. Every email has a final status at most 48 hours after sending; poll every 15 minutes at most (each call counts against your API quota) or use the email.delivered / email.bounced webhooks. Only the client that sent the email can read its status — any other id returns 404.

Parameters

Responses

Example 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

Send email campaign

Sends a bulk email campaign to one or more contact lists.

Required:

• id_message — the template to send (from GET /Message)
• id_sender_email — the sender address (from GET /SenderEmail)
• lists — at least one target contact list
• campaign_title — label for statistics tracking

Segment: optionally filter recipients by a saved segment (id_segment). The segment filters contacts within the specified lists.

Scheduling: set date_planned to a future ISO 8601 date/time. Campaigns can be edited or cancelled until 5 minutes before the scheduled time.

Request body (application/json)

Example

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

Responses

Example 200

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

GET /Send

List scheduled sends

Returns the list of email campaigns waiting to be sent (scheduled, not yet processed).

Parameters

Responses

DELETE /Send/{id}

Cancel a scheduled send

Cancels and deletes a scheduled email send that has not yet been processed. Cannot cancel sends that are currently being processed.

Parameters

Responses

GET /Send/Mail/Scheduled

List scheduled single emails

Returns the single emails sent with POST /Send/Mail and a future date that have not left yet. Campaigns are listed by GET /Campaign/Scheduled.

OAuth scope : email:send

Responses

Example 200

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

POST /Send/Mail/{id}/Cancel

Cancel a scheduled single email

Cancels the email as long as it has not left.

OAuth scope : email:send

Parameters

Responses

Example 200

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

PATCH /Send/Mail/{id}/Reschedule

Reschedule a scheduled single email

Changes the send date. The new date must be in the future and within 90 days. POST is also accepted.

OAuth scope : email:send

Parameters

Request body (application/json)

Responses

Example 200

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

GET /SenderEmail

List sender addresses

Returns the validated sender email addresses configured for the account.

Parameters

Responses

Example 200

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

POST /SenderEmail

Add a sender address

Adds the address with the same checks as the app and sends it a validation email. It can be used once the link in that email is clicked. An account can have up to 25 senders, validated or pending.

OAuth scope : email:templates:write

Request body (application/json)

Responses

Example 200

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

POST /SenderEmail/{id}/ResendValidation

Send the validation email again

For an address still waiting for validation.

OAuth scope : email:templates:write

Parameters

Responses

Example 200

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

GET /SenderEmail/{id}/Authentication

Check the domain of a sender (SPF, DKIM, DMARC, MX)

Checks the domain live in DNS and returns the records to publish. Read-only. DKIM is activated in the app: dkim_settings_url opens the right screen.

OAuth scope : email:templates:read

Parameters

Responses

Example 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

List email sending history

Returns the log of past email sends for the account.

Parameters

Responses

GET /History/SMS

List SMS sending history

Returns the log of past SMS sends for the account.

Parameters

Responses

GET /Segment

List segments

Returns all saved dynamic segments for the account.

OAuth scope : contacts:read

Parameters

Responses

GET /Segment/{id}/Contact

List the contacts of a segment

With id_list, returns only the contacts of that list in the segment: those a campaign list + segment would reach. The total is in the X-Total-Count header.

OAuth scope : contacts:read

Parameters

Responses

GET /Segment/{id}/Count

Count the contacts of a segment

The number only, to know the size of a send beforehand. With id_list, counts only the contacts of that list in the segment.

OAuth scope : contacts:read

Parameters

Responses

Example 200

{
  "total": 1250
}

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

Check if a contact matches a segment

Verifies whether a specific contact (by GUID) currently matches the rules of a given segment. Useful for triggering automation logic on demand.

OAuth scope : contacts:read

Parameters

Responses

POST /Sms/SingleSMS

Send single SMS

Sends a single SMS to one phone number directly. Use this for transactional messages (OTPs, order confirmations, alerts). The phone number accepts +41…, 0041… or 41… with or without separators — see Phone number format in the API description for accepted / rejected inputs.

Request body (application/json)

Example

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

Responses

POST /Sms/Campaign

Send SMS campaign

Sends an SMS message to the phone_number field of all contacts in one or more lists. Contacts without a phone number are skipped.

Request body (application/json)

Example

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

Responses

GET /Sms

List SMS history

Returns the log of SMS sends (both single and campaign) for the account.

Parameters

Responses

DELETE /Sms/{id}

Cancel a scheduled SMS

Cancels a pending scheduled SMS send.

Parameters

Responses

GET /Sms/Scheduled

List scheduled SMS sends

Returns SMS sends with a future date_planned (not yet dispatched), ordered by date ascending.

Parameters

Responses

POST /Sms/{id}/Cancel

Cancel a scheduled SMS

Cancels a scheduled SMS send only if it has not yet been dispatched.

Parameters

Responses

PATCH /Sms/{id}/Reschedule

Reschedule a scheduled SMS

Updates the planned send date of a scheduled SMS. The new date must be in the future and within 90 days. Fails if the SMS has already been dispatched.

Body field name: the API accepts date_planned (snake_case, primary) as well as the legacy aliases PlanDate and scheduled_time. Provide any one of them.

Parameters

Request body (application/json)

Responses

GET /FolderList

List list folders

Returns the folders used to organize contact lists.

Parameters

Responses

GET /FolderList/{id}

Get a single list folder

Returns the details of one list folder by its ID.

Parameters

Responses

GET /FolderMessage

List message folders

Returns the folders used to organize email message templates.

Parameters

Responses

POST /Import/Upload

Upload a contacts file (CSV / XLSX) for bulk import

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

Request type: multipart/form-data

Required form fields:

• id_list (integer) — target list ID
• file (binary) — the CSV or XLSX file to upload
• json_match_fields (string, JSON) — which column of the file goes to which contact field. email_position = 0-based column holding the email (required), phone_position = column holding the mobile number or -1, fields = ids of the other fields (see GET /Field), fields_position = column of each of them, update_fields = update existing contacts. A missing or invalid mapping returns 400 and no import job is created.

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 may hold headers (detected automatically: a first row without any email address is skipped)
• Columns are mapped by json_match_fields
• Max file size: 50 MB

Request body (multipart/form-data)

Responses

Example 200

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

GET /Webhook

List webhooks

Returns every webhook configured on the authenticated account.

Responses

POST /Webhook

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": [
    "email.delivered",
    "email.bounced",
    "contact.created"
  ],
  "description": "Slack integration"
}

Responses

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

Get a webhook

Parameters

Responses

PUT /Webhook/{id}

Update a webhook

Partial update — only the sent fields are modified.

Parameters

Request body (application/json)

Responses

DELETE /Webhook/{id}

Delete a webhook

Permanently deletes the webhook and its full delivery history.

Parameters

Responses

POST /Webhook/{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 /Webhook/{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 /Webhook/{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 /Webhook/{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 (10s → 1min → 5min → 30min → 2h → 6h → 24h, then abandoned).

Parameters

Responses

GET /Suppression/Bounces

List the bounces of the account

Most recent first. The total is in the X-Total-Count header.

OAuth scope : email:read

Parameters

Responses

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

Remove a bounce

source and type are required, as returned by GET /Suppression/Bounces: an id alone is not unique.

OAuth scope : contacts:write

Parameters

Responses

Example 200

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

POST /Suppression/Bounces/{id}/Restore

Put a contact with a hard bounce back in its lists

Only for a hard bounce with the source contact.

OAuth scope : contacts:write

Parameters

Responses

Example 200

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

GET /Suppression/Unsubscribers

List the unsubscribers of the account

Most recent first. The total is in the X-Total-Count header.

OAuth scope : contacts:read

Parameters

Responses

Example 200

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

POST /Suppression/Unsubscribers

Add an unsubscriber

Without id_list, the address is unsubscribed for the whole account. With it, from that unsubscribe list only.

OAuth scope : contacts:write

Request body (application/json)

Responses

Example 200

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

DELETE /Suppression/Unsubscribers/{id}

Remove an unsubscriber

source is required, as returned by GET /Suppression/Unsubscribers: an id alone is not unique.

OAuth scope : contacts:write

Parameters

Responses

Example 200

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