Skip to main content

REST API

WhautoMail provides a powerful REST API so you can integrate your account with external systems, automate email operations, and build custom solutions on top of your marketing workflows.

What Can You Do with the REST API?​

With the WhautoMail REST API, you can:

  • Add and manage contacts (create, update, and retrieve)
  • Subscribe to webhooks to receive real-time event notifications (for example: contact created, contact tag added or contact tag removed)
  • Manage Contact Tags (add, remove, and list tags on contacts)
  • Integrate with third-party platforms (CRM, internal tools, etc.)

API Host​

Use the correct API host when integrating with WhautoMail:

To confirm your exact API host, open the Integrations REST API section in your WhautoMail dashboard and copy the hostname shown there. Always use the host assigned to your account for best performance and reliability.

API Key Authentication (x-api-key Header)​

All WhautoMail API requests require an API key for authentication. This ensures secure, authorized access to your account.

How to generate and use your API key:

  1. In WhautoMail, go to Integrations REST API.
  2. Click New API Key, give it a name, and generate it.
  3. When making API requests, include the key in the x-api-key header.

Example:

curl -X GET 'https:/yourendpoint.com/rest/some_endpoint' \
  -H 'x-api-key: YOUR_API_KEY'

API Rate Limits​

To maintain stability and fairness, WhautoMail applies rate limits to API usage:

Type of AccountRequests per minute (RPM)Requests per day (RPD)
Subscribed Account100144,000
  • These limits help protect the platform from abuse and overload.
  • For higher or custom enterprise limits, contact support (additional costs may apply).

Endpoints​

Base URL​

All endpoints below are exposed under your REST base path, for example:

https://yourendpoint.com/rest/v1/...

Account Info​

  • GET /v1/account-info
    • Returns basic information about the authenticated account (such as name, and ownerEmail).
GET /rest/v1/account-info HTTP/1.1
Host: yourendpoint.com
x-api-key: YOUR_API_KEY
curl -X GET 'https://yourendpoint.com/rest/v1/account-info' \
  -H 'x-api-key: YOUR_API_KEY'

Contact Tags​

Manage Contact Tags for your account.

  • POST /v1/contact-tags
    • Create a new Contact Tag.
    • Body (JSON): { "name": "TAG_NAME" }
    • Responses:
      • 201 Created – Contact Tag created.
      • 400 Bad Request – name is missing.
{
  "name": "VIP"
}
curl -X POST 'https://yourendpoint.com/rest/v1/contact-tags' \
  -H 'x-api-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "VIP"
  }'
  • GET /v1/contact-tags
    • List Contact Tags.
    • Query params:
      • searchText (optional)
      • page (optional, default 1)
      • limit (optional, default 10, max 100)
curl -X GET 'https://yourendpoint.com/rest/v1/contact-tags?page=1&limit=10' \
  -H 'x-api-key: YOUR_API_KEY'
  • GET /v1/contact-tags/{contactTagId}
    • Get a single Contact Tag.
curl -X GET 'https://yourendpoint.com/rest/v1/contact-tags/{contactTagId}' \
  -H 'x-api-key: YOUR_API_KEY'
  • DELETE /v1/contact-tags/{contactTagId}
    • Delete a Contact Tag.
curl -X DELETE 'https://yourendpoint.com/rest/v1/contact-tags/{contactTagId}' \
  -H 'x-api-key: YOUR_API_KEY'

Contacts​

Create, list, retrieve, update, and delete Contacts, and manage their tags.

  • POST /v1/contacts
    • Create a Contact.
    • Body (JSON) fields (key ones):
      • name, email, workspace: { id } (required)
      • stage, tags[], notes, customFields, status (optional)
{
  "name": "John Doe",
  "email": "john@example.com",
  "workspace": { "id": "WORKSPACE_ID" },
  "stage": "lead",
  "tags": ["customer", "newsletter"],
  "notes": "First contacted via webinar",
  "customFields": {
    "company": "Acme Inc"
  },
  "status": "active"
}
curl -X POST 'https://yourendpoint.com/rest/v1/contacts' \
  -H 'x-api-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "John Doe",
    "email": "john@example.com",
    "workspace": { "id": "WORKSPACE_ID" },
    "tags": ["customer", "newsletter"]
  }'
  • GET /v1/contacts
    • List Contacts.
    • Query params (main ones):
      • workspaceId, channel (default all), searchText, tags (comma-separated), page, limit (max 100).
curl -X GET 'https://yourendpoint.com/rest/v1/contacts?page=1&limit=10' \
  -H 'x-api-key: YOUR_API_KEY'
  • GET /v1/contacts/{contactId}
    • Get a single Contact by id.
curl -X GET 'https://yourendpoint.com/rest/v1/contacts/{contactId}' \
  -H 'x-api-key: YOUR_API_KEY'
  • PUT /v1/contacts/{contactId}
    • Update a Contact (same shape as create body).
{
  "name": "Jane Doe",
  "email": "jane@example.com",
  "workspace": { "id": "WORKSPACE_ID" },
  "stage": "customer",
  "tags": ["vip"],
  "notes": "Upgraded plan",
  "customFields": {
    "company": "Acme Inc"
  },
  "status": "active"
}
curl -X PUT 'https://yourendpoint.com/rest/v1/contacts/{contactId}' \
  -H 'x-api-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Jane Doe",
    "email": "jane@example.com",
    "workspace": { "id": "WORKSPACE_ID" },
    "tags": ["vip"]
  }'
  • DELETE /v1/contacts/{contactId}
    • Delete a Contact.
curl -X DELETE 'https://yourendpoint.com/rest/v1/contacts/{contactId}' \
  -H 'x-api-key: YOUR_API_KEY'
  • POST /v1/contacts/{contactId}/tags/add
    • Add tags to a Contact.
    • Body (JSON): { "tags": ["TAG_1", "TAG_2", ...] }
{
  "tags": ["vip", "newsletter"]
}
curl -X POST 'https://yourendpoint.com/rest/v1/contacts/{contactId}/tags/add' \
  -H 'x-api-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "tags": ["vip", "newsletter"]
  }'
  • POST /v1/contacts/{contactId}/tags/remove
    • Remove tags from a Contact.
    • Body (JSON): { "tags": ["TAG_1", "TAG_2", ...] }
{
  "tags": ["vip"]
}
curl -X POST 'https://yourendpoint.com/rest/v1/contacts/{contactId}/tags/remove' \
  -H 'x-api-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "tags": ["vip"]
  }'

Webhooks​

Configure webhooks to receive events (for example, contact created, tag added/removed).

  • POST /v1/webhooks
    • Create a Webhook.
    • Body (JSON) fields (all required):
      • name – Webhook name.
      • serverUrl – HTTPS endpoint that will receive events.
      • events[] – Array of event types to subscribe to. Allowed values:
        • webhook_contact_created – Triggered when a new contact is created.
        • webhook_contact_tag_added – Triggered when a tag is added to a contact.
        • webhook_contact_tag_removed – Triggered when a tag is removed from a contact.
      • webhookHeaders[] – Array of headers (key/value) to send with each request.
      • active – Boolean flag to enable/disable the webhook.
{
  "name": "Contact events webhook",
  "serverUrl": "https://example.com/webhooks/whautomail",
  "events": [
    "webhook_contact_created",
    "webhook_contact_tag_added",
    "webhook_contact_tag_removed"
  ],
  "webhookHeaders": [
    { "key": "X-Auth-Token", "value": "SECRET" }
  ],
  "active": true
}
curl -X POST 'https://yourendpoint.com/rest/v1/webhooks' \
  -H 'x-api-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Contact events webhook",
    "serverUrl": "https://example.com/webhooks/whautomail",
    "events": ["webhook_contact_created"],
    "webhookHeaders": [{ "key": "X-Auth-Token", "value": "SECRET" }],
    "active": true
  }'
  • PUT /v1/webhooks/{webhookId}
    • Update a Webhook (same body as create).
{
  "name": "Updated Contact events webhook",
  "serverUrl": "https://example.com/webhooks/whautomail",
  "events": [
    "webhook_contact_created",
    "webhook_contact_tag_added"
  ],
  "webhookHeaders": [
    { "key": "X-Auth-Token", "value": "SECRET" }
  ],
  "active": true
}
curl -X PUT 'https://yourendpoint.com/rest/v1/webhooks/{webhookId}' \
  -H 'x-api-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Updated Contact events webhook",
    "serverUrl": "https://example.com/webhooks/whautomail",
    "events": ["webhook_contact_created"],
    "webhookHeaders": [{ "key": "X-Auth-Token", "value": "SECRET" }],
    "active": true
  }'
  • GET /v1/webhooks
    • List Webhooks.
    • Query params: page, limit (max 100).
curl -X GET 'https://yourendpoint.com/rest/v1/webhooks?page=1&limit=10' \
  -H 'x-api-key: YOUR_API_KEY'
  • GET /v1/webhooks/{webhookId}
    • Get a single Webhook.
curl -X GET 'https://yourendpoint.com/rest/v1/webhooks/{webhookId}' \
  -H 'x-api-key: YOUR_API_KEY'
  • DELETE /v1/webhooks/{webhookId}
    • Delete a Webhook.
curl -X DELETE 'https://yourendpoint.com/rest/v1/webhooks/{webhookId}' \
  -H 'x-api-key: YOUR_API_KEY'