API Reference

The Mailtea REST API.

The Mailtea REST API lets you send transactional and marketing email, manage contacts and audiences, verify sending domains, render templates, and subscribe to webhook events. It is organized around predictable, resource-oriented URLs, accepts and returns JSON, and uses standard HTTP response codes and verbs.

Base URL

All API requests are made to a single base URL, and every endpoint lives under the /v1 prefix:

https://api.mailtea.app

For example, sending an email is a POST to https://api.mailtea.app/v1/emails.

Authentication

Authenticate every request with a Bearer token in the Authorization header. A token is either a personal access token (prefix mt_pat_) or a service key (prefix mt_svc_):

curl https://api.mailtea.app/v1/emails \
  -H "Authorization: Bearer mt_pat_xxxxxxxx" \
  -H "Content-Type: application/json"

Each token carries a set of scopes (for example issues:send, contacts:write, domains:read) that determine which operations it can perform. The required scope is listed on each endpoint's reference page.

If your account belongs to more than one team, you can pin a request to a specific team with the optional x-mailtea-organization-id header:

curl https://api.mailtea.app/v1/posts \
  -H "Authorization: Bearer mt_pat_xxxxxxxx" \
  -H "x-mailtea-organization-id: team_xxxxxxxx"

See Authentication for how to create tokens, the full list of scopes, and how teams and publications are resolved.

Errors

Mailtea uses conventional HTTP status codes to indicate the result of a request: 2xx for success, 4xx for a problem with the request (such as a missing field, an invalid token, or insufficient scope), and 5xx for an error on Mailtea's side. Failed requests return a JSON body describing what went wrong.

See Errors for the full error format and a reference of status codes.

Pagination

List endpoints are paginated. Most collections use cursor-based pagination: pass a limit to control page size and an after cursor to fetch the next page. The response is a list object that tells you whether more results are available:

{
  "object": "list",
  "data": [],
  "has_more": true,
  "next_cursor": "ct_xxxxxxxx"
}

To page through results, repeat the request with after set to the previous response's next_cursor, and stop once has_more is false.

A limit or offset that is not a number returns 400 with code: "limit_invalid" or "offset_invalid", and a cursor that cannot be decoded returns 400 with code: "cursor_invalid" — while a numeric limit outside an endpoint's range is clamped to it rather than refused. See Errors.

Posts are an exception: the list posts endpoint uses offset-based pagination with limit and offset, and returns a total count alongside data.

Rate limits

API requests are subject to rate limits. See Rate limits for the current limits and guidance on handling them.

Versioning

The /v1 prefix in every path is the API version. We aim to make backward-compatible changes within a version — adding new endpoints, optional fields, and event types without breaking existing integrations. Any breaking change ships under a new version prefix, so code written against /v1 keeps working.

Resources

Resource	Description
Emails	Send, schedule, and track transactional email.
Posts	Create, schedule, and send newsletters and broadcasts.
Contacts	Manage subscribers for a publication.
Subscribe	Public signup and double-opt-in confirmation, no API token.
Segments	Target marketing sends to subsets of your audience.
Topics	Organize contacts and manage subscription preferences.
Contact properties	Define team-wide custom fields for personalization.
Templates	Store and render reusable email templates.
Domains	Verify sending and tracking domains.
Webhooks	Receive real-time email and contact events.
API keys	Create and revoke keys for API access.
Automations	Build, start, and observe multi-step contact automations.
Automation runs	Inspect and cancel individual contacts' automation runs.
Events	Send custom events that trigger automations.

Working examples

Every endpoint on this page is exercised by a runnable project under mailtea-app. Start with mailtea-curl-example for the raw HTTP calls, or pick your stack from Examples.

API Reference

On this page