API reference

The Emailit API is a REST API served over HTTPS. You send JSON, you get JSON back, and you authenticate every request with a Bearer token. Use it to send email and to manage everything else in a workspace: sending domains, API keys, contacts, audiences, campaigns, templates, webhooks and more.

Base URL

Every request goes to the version 2 base URL:

https://api.emailit.com/v2

Paths in this reference are relative to it. For example, POST /emails means POST https://api.emailit.com/v2/emails.

Make your first request

This request sends one email. Replace the sender with an address on a verified sending domain and set EMAILIT_API_KEY to one of your API keys.

curl https://api.emailit.com/v2/emails \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "Acme <hello@acme.com>",
    "to": "ada@example.com",
    "subject": "Welcome to Acme",
    "html": "<p>Thanks for signing up.</p>"
  }'

import { Emailit } from '@emailit/node';

const emailit = new Emailit(process.env.EMAILIT_API_KEY);

const email = await emailit.emails.send({
  from: 'Acme <hello@acme.com>',
  to: 'ada@example.com',
  subject: 'Welcome to Acme',
  html: '<p>Thanks for signing up.</p>',
});

import os
from emailit import EmailitClient

client = EmailitClient(os.environ["EMAILIT_API_KEY"])

email = client.emails.send({
    "from": "Acme <hello@acme.com>",
    "to": "ada@example.com",
    "subject": "Welcome to Acme",
    "html": "<p>Thanks for signing up.</p>",
})

The response is the new email object with its ID (em_…) and status accepted. See Send an email for every option.

Authentication

Pass an API key or an OAuth access token in the Authorization header:

Authorization: Bearer secret_••••••••••••••••••••••••••••••••

API keys start with secret_ and belong to one workspace. A key has the full scope (every endpoint) or the sending scope (send endpoints only), and a sending key can be restricted to one sending domain. Requests without a valid key fail with 401. See Authentication.

Requests and responses

• JSON in, JSON out. Send request bodies as JSON with Content-Type: application/json. A body that isn’t valid JSON returns 400 with the message Invalid JSON in request body. The maximum request body is 50 MB.
• Methods. GET reads, POST creates and updates, and DELETE deletes. The API doesn’t use PUT or PATCH.
• Objects. Every object has an object field that names its type (email, domain, api_key, audience, subscriber, contact, …) and an id.
• Timestamps. Dates are ISO 8601 strings in UTC with microsecond precision, for example 2026-10-01T09:30:12.482913Z. Fields that aren’t set are null.
• Lists. List endpoints are paginated and most accept filters and sorting. See Pagination and Filtering.
• Errors. Failed requests return a 4xx or 5xx status code and a JSON body that explains the problem. See Errors.

Object IDs

IDs are strings made of a type prefix and 27 letters and digits, for example em_4KYof1ZzXndZE2VPi0DgULiekG8. IDs are case-sensitive and roughly ordered by creation time.

Some resources also accept a readable identifier in the path. Domains, API keys, audiences, campaigns and webhooks accept their name (GET /domains/acme.com). Contacts and suppressions accept an email address, and subscribers accept the contact’s email address. URL-encode names and addresses that contain special characters. Domains created before the switch to dom_ IDs keep their sd_ or sed_ ID, and those IDs still work.

Versioning

The current version is v2, and it’s part of the base URL. New fields and endpoints are added to v2 without a version change, so write clients that ignore fields they don’t recognize. See Versioning.

Resources

For a single table of every endpoint and the scope it needs, see All endpoints.

SDKs

Official libraries wrap the API for the most common languages. They’re open source on GitHub.

Webhooks and events

Instead of polling for status changes, register a webhook and Emailit posts signed batches of events to your endpoint as they happen: deliveries, bounces, opens, clicks, new contacts and more. The same events are available from List events. See Event types for the full list.

MCP server

The hosted MCP server at https://api.emailit.com/mcp lets AI assistants such as ChatGPT, Claude, Cursor, Codex and Grok call this API on your behalf: 109 tools cover every resource on this page. Assistants sign in with OAuth or use an API key, with the same scopes. See MCP server and the tool reference.

Related