# API reference

> The Emailit REST API at a glance. Base URL, authentication, JSON requests and responses, object IDs, versioning and every resource you can manage.

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:

```text
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](/docs/domains/verification/) and set `EMAILIT_API_KEY` to one of your [API keys](/docs/developers/api-keys/).

**cURL**

```bash
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>"
  }'
```

**Node.js**

```javascript
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>',
});
```

**Python**

```python
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](/docs/api-reference/emails/send/) for every option.

## Authentication

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

```http
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](/docs/api-reference/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](/docs/api-reference/pagination/) and [Filtering](/docs/api-reference/filtering/).
- **Errors.** Failed requests return a `4xx` or `5xx` status code and a JSON body that explains the problem. See [Errors](/docs/api-reference/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.

| Prefix | Object | Prefix | Object |
| --- | --- | --- | --- |
| `em_` | Email | `aud_` | Audience |
| `dom_` | Sending domain | `sub_` | Subscriber |
| `key_` | API key | `con_` | Contact |
| `tem_` | Template | `cmp_` | Campaign |
| `sup_` | Suppression | `frm_` | Form |
| `wh_` | Webhook | `fsub_` | Form submission |
| `whr_` | Webhook request | `aut_` | Automation |
| `evt_` | Event | `aur_` | Automation run |
| `dmr_` | DMARC report | `ev_` | Email verification |
| `evl_` | Verification list | | |

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](/docs/api-reference/versioning/).

## Resources

  - [Emails](/docs/api-reference/emails/): Send email, read messages and their content, and schedule, cancel, retry or forward them.
  - [Domains](/docs/api-reference/domains/): Add sending domains, read their DNS records and verify them.
  - [DMARC reports](/docs/api-reference/dmarc/): Read aggregate and forensic DMARC reports for a domain, or upload your own.
  - [API keys](/docs/api-reference/api-keys/): Create, rename, regenerate and delete the API keys of a workspace.
  - [Audiences](/docs/api-reference/audiences/): Manage the subscriber lists used by campaigns and sign-up forms.
  - [Subscribers](/docs/api-reference/audiences/subscribers/): Add, update and remove the subscribers of an audience.
  - [Contacts](/docs/api-reference/contacts/): Manage contact profiles and custom fields, one at a time or in bulk.
  - [Campaigns](/docs/api-reference/campaigns/): Create campaigns, choose their audiences, and send or schedule them.
  - [Automations](/docs/api-reference/automations/): Build workflows from triggers and steps, run them and inspect their runs.
  - [Forms](/docs/api-reference/forms/): Create sign-up forms, publish them and rotate their public token.
  - [Templates](/docs/api-reference/templates/): Create template versions, publish one per alias and send with it.
  - [Suppressions](/docs/api-reference/suppressions/): Read and manage the addresses Emailit won't send to.
  - [Webhooks](/docs/api-reference/webhooks/): Register endpoints that receive signed event notifications.
  - [Events](/docs/api-reference/events/): Read the event stream behind webhooks: deliveries, bounces, opens and more.
  - [Email verification](/docs/api-reference/email-verifications/): Verify a single address in real time.
  - [Verification lists](/docs/api-reference/email-verifications/lists/): Verify up to 10,000 addresses at once and export the results.

For a single table of every endpoint and the scope it needs, see [All endpoints](/docs/api-reference/endpoints/).

## SDKs

Official libraries wrap the API for the most common languages. They're open source on [GitHub](https://github.com/emailit).

| Language | Package | Guide |
| --- | --- | --- |
| Node.js | `@emailit/node` | [Node.js](/docs/frameworks/nodejs/) |
| Python | `emailit` | [Python](/docs/frameworks/python/) |
| PHP | `emailit/emailit-php` | [PHP](/docs/frameworks/php/) |
| Laravel | `emailit/emailit-laravel` | [Laravel](/docs/frameworks/laravel/) |
| Ruby | `emailit` | [Ruby on Rails](/docs/frameworks/rails/) |
| Go | `github.com/emailit/emailit-go/v2` | [Go](/docs/frameworks/go/) |
| Java | `com.emailit` | [Java](/docs/frameworks/java/) |
| .NET | `Emailit` | [.NET](/docs/frameworks/dotnet/) |
| Rust | `emailit` | [SDKs](/docs/sdks/) |

## Webhooks and events

Instead of polling for status changes, register a [webhook](/docs/webhooks/) 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](/docs/api-reference/events/list/). See [Event types](/docs/webhooks/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](/docs/mcp/) and the [tool reference](/docs/mcp/tools/).

## Related

  - [Authentication](/docs/api-reference/authentication/): API keys, scopes, domain restrictions and OAuth tokens.
  - [Rate limits](/docs/api-reference/rate-limits/): Sending limits, response headers and how to back off.
  - [Errors](/docs/api-reference/errors/): Error formats, status codes and common fixes.
  - [Send your first email](/docs/quickstart/api/): A step-by-step quickstart from API key to inbox.

---
Source: https://emailit.com/docs/api-reference/