Developer overview

This page collects the conventions you need before you write code against Emailit: where the API lives, how requests are authenticated, how objects are identified, and how errors, pagination and rate limits work. Each section links to the detailed reference.

Ways to integrate

Not sure whether to use the API or SMTP? Read API or SMTP.

Base URL and versioning

All REST endpoints live under one base URL:

https://api.emailit.com/v2

v2 is the current and only documented version. The legacy v1 API is deprecated; see Versioning.

Authentication

Send an API key as a bearer token in the Authorization header of every request:

curl https://api.emailit.com/v2/domains \
  -H "Authorization: Bearer $EMAILIT_API_KEY"

• API keys start with secret_. Older keys without the prefix keep working.
• Each key belongs to one workspace and has a scope: Full Access (full) can call every endpoint, Sending Only (sending) can only send and manage sends. See API keys.
• OAuth access tokens issued to OAuth apps are accepted in the same header.
• A missing key returns 401 with API key required, an unknown key returns 401 with Invalid API key, and a suspended workspace returns 403 with Workspace is suspended.

Never call the API from a browser or mobile app with your key. Keep it on your server. Details: Authentication.

IDs and prefixes

Every object has a string ID with a type prefix, so you can tell what an ID refers to at a glance.

Domains created before the switch to dom_ IDs can still have sd_ or sed_ IDs.

Some endpoints also accept a human-readable identifier in place of the ID: a name for API keys, domains, webhooks, campaigns and audiences, and an email address for contacts and suppressions. Emails, templates and events are looked up by ID only.

Requests and responses

• JSON in, JSON out. Send request bodies as JSON with Content-Type: application/json. Malformed JSON returns 400 with Invalid JSON in request body. A request body can be up to 50 MB; an email’s final MIME message can be up to 40 MB.
• Errors. Most errors return {"statusCode", "error", "message"}. Validation errors add a details array, and sending errors return validation_errors. Plan-gated features return 403 with "error": "plan_required". See Errors.
• Pagination. List endpoints take page and limit (1 to 100) and return data, next_page_url and previous_page_url. Templates and automations use page and per_page. See Pagination.
• Filtering and sorting. Filter with field.condition=value, combine filters with match=all or match=or, and sort with order and direction. For example, GET /v2/emails?status.exact=bounced&order=created_at&direction=desc. See Filtering.
• Idempotency. Send an Idempotency-Key header on POST /emails and POST /emails/:id/forward to make retries safe. Emailit replays the first response for 24 hours. See Idempotency.
• Rate limits. Sending is limited per workspace, by default to 2 emails per second and 5,000 emails per day, shared between the API and SMTP. Responses include ratelimit-* headers, and a 429 includes retry-after. See Rate limits and Limits.

SDKs

Official libraries wrap the REST API for Node.js, PHP, Laravel, Python, Ruby, Go, Java, .NET and Rust. They all live on GitHub. See SDKs and libraries for install commands, and the framework guides for complete examples, starting with Node.js.

Webhooks

Webhooks push events to your endpoint as they happen: deliveries, bounces, opens, clicks, inbound mail, and changes to domains, contacts and other resources. Each request carries a JSON array of up to 100 events and is signed with HMAC-SHA256 in the X-Emailit-Signature header. Failed requests are retried for up to 11 attempts. Start with Set up a webhook and Request signature.

MCP server and AI tools

The hosted MCP server at https://api.emailit.com/mcp gives AI assistants 109 tools covering the full API v2, from sending email to campaigns and automations. Assistants sign in with OAuth or an API key, and the Emailit plugins add skills for ChatGPT, Codex, Claude Code, Cursor and Grok.

The docs are also published for AI: every page has a Markdown version, and /docs/llms.txt indexes them all.

Next steps