Docs/API Reference/Authentication

Authentication

All API requests must be authenticated with an API key. Keys are workspace-scoped and can be granted fine-grained permissions using scopes.

API Keys

API keys in EmailSendX are workspace-scoped, not user-scoped. A key belongs to a specific workspace and can only read and write data within that workspace. If you manage multiple workspaces, each workspace has its own set of keys.

A single workspace can have multiple active API keys — useful for giving different services or team members separate keys with different permission scopes. You can revoke individual keys without affecting others.

Creating API Keys

To create a new API key:

Go to Workspace Settings → API → New API Key.
Give the key a descriptive name (e.g., zapier-integration or backend-server).
Select the permission scopes the key should have. Grant only the scopes your integration actually needs.
Optionally, restrict the key to one or more IP addresses or CIDR ranges.
Click Create Key. Copy the key immediately — it will only be shown once.

Copy your key immediately

The full API key is only shown once at creation time. After you navigate away, only the key prefix is shown. If you lose it, delete the key and create a new one.

Key Format

EmailSendX API keys use a consistent prefix to make them easy to identify:

Prefix	Environment	Description
esx_live_	Production	Live workspace key — affects real data
esx_test_	Test	Test workspace key — safe for development

A full production key looks like: esx_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6

Bearer Token Method

Pass your API key as a Bearer token in the Authorization header. This is the standard OAuth-style approach and the recommended method.

bash

Authorization: Bearer esx_live_your_key_here

x-api-key Header Method

Alternatively, pass the key directly in the x-api-key header. Useful when working with tools or proxies that don't support the Authorization header.

bash

x-api-key: esx_live_your_key_here

Full examples in multiple languages:

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

# Using x-api-key
curl -X GET https://emailsendx.com/api/v1/contacts \
  -H "x-api-key: esx_live_your_key_here"

Never expose API keys in client-side code

Never include your API key in browser JavaScript, mobile app bundles, or public repositories. Use environment variables and only call the API from your server-side code.

Verify your key

Use the GET /api/v1/whoami endpoint to verify your key is valid and check which scopes it has. Returns a 401 if the key is invalid or revoked.

Scopes

Each API key can be restricted to a subset of permissions. Assign only the scopes your integration needs to minimize the blast radius of a compromised key.

Scope	Allows
contacts:read	Read contact profiles, metadata, and activity
contacts:write	Create, update, and upsert contacts; fire custom events
lists:read	List and retrieve list objects
lists:write	Create new lists
campaigns:read	Read campaign details and stats
templates:read	Read email template content
segments:read	List and retrieve segment objects
automations:read	List automations and view their config
automations:write	Enroll contacts in automations

If a key attempts an action it lacks scope for, the API returns 403 Forbidden with an error message indicating the missing scope.

IP Restriction

When creating or editing a key, you can optionally restrict it to specific IP addresses or CIDR ranges. Requests from any other IP will receive a 401 Unauthorized response.

This is especially valuable for server-to-server integrations where your server has a static IP. It adds a layer of protection even if the key leaks.

bash

# Example CIDR ranges you might restrict to:
203.0.113.42/32      # Single IP
10.0.0.0/8           # Private network range
198.51.100.0/24      # Subnet

Test before locking down

If you restrict to the wrong IP, all API calls from that key will fail immediately. Verify your server's outbound IP before saving IP restrictions.

Key Rotation

To rotate an API key:

Create a new key in Settings → API → New API Key with the same scopes.
Update your application or integration to use the new key.
Verify everything works with the new key.
Delete the old key from Settings → API.

Deletion is immediate

Deleting an API key takes effect immediately. Any system still using the old key will start receiving 401 Unauthorized errors. There is no deprecation grace period — plan your cutover carefully.

Ready to make your first API call?

Your API key is in workspace Settings → API. Use the /whoami endpoint to verify it's working.

Browse API Reference View rate limits