API Reference

The EmailSendX API is a RESTful HTTP API that accepts JSON request bodies and returns JSON responses. All API access is workspace-scoped — your API key belongs to a specific workspace and can only access data within that workspace.

The API is versioned. The current version is v1, and breaking changes will only be introduced under a new version prefix. Non-breaking additions (new fields, new endpoints) may be added at any time.

Key resources in the API:

• Contacts — create, upsert, and manage subscribers
• Lists — organize contacts into named groups
• Segments — read dynamic filter-based audiences
• Campaigns — retrieve campaign stats for reporting
• Automations — enroll contacts in automation workflows
• Events — fire custom events to trigger automations

All API requests are made to the following base URL. Append the endpoint path after it.

https://emailsendx.com/api/v1

For example, to list contacts: GET https://emailsendx.com/api/v1/contacts

All API requests require authentication using an API key. You can pass the key as a Bearer token in the Authorization header, or as a value in the x-api-key header.

API keys are created per workspace in Settings → API → New API Key. Each key can be scoped to specific permissions.

All requests must set the Content-Type: application/json header when sending a request body. GET requests do not require a body.

• Request bodies must be valid JSON objects.
• Query string parameters are used for filtering and pagination on GET endpoints.
• All strings are UTF-8 encoded.
• Dates must be provided in ISO 8601 format (2026-01-15T10:00:00Z).

All responses are JSON with Content-Type: application/json.

Single resource response:

{
  "data": {
    "id": "cuid_example",
    "email": "john@example.com",
    "firstName": "John"
  }
}

List response with pagination:

{
  "data": [
    { "id": "cuid_1", "email": "alice@example.com" },
    { "id": "cuid_2", "email": "bob@example.com" }
  ],
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 248,
    "totalPages": 5
  }
}

Error response:

{
  "error": "Invalid email address"
}

List endpoints are paginated. Use the page and limit query parameters to control which page and how many results to return.

The response always includes a pagination object with total and totalPages so you can determine when to stop iterating.

The API enforces a rate limit of 120 requests per minute per API key, using a sliding window algorithm. Rate limit headers are included on every response.

When you exceed the limit, you receive a 429 Too Many Requests response with a Retry-After header indicating how many seconds to wait.

The API uses standard HTTP status codes. The response body always includes an error field with a human-readable message when something goes wrong.

See the full Errors & Status Codes reference for common error messages and troubleshooting tips.

The full machine-readable OpenAPI 3.1 spec is hosted at /api/v1/openapi.json. Use it to generate client SDKs, import into Postman or Insomnia, or drive automated tests.

Download the OpenAPI spec →

Verify your API key is working with the /whoami endpoint:

curl -X GET https://emailsendx.com/api/v1/whoami \
  -H "Authorization: Bearer esx_live_your_key_here"