API overview

EmailFlow AI ships a complete developer platform on every plan: a resource-oriented REST API with scoped keys, uniform errors, idempotency, and webhooks — plus a typed SDK, an OpenAPI 3.1 spec, and llms.txt guides for AI agents. The same endpoints the app itself uses.

Base URL and versioning

Every endpoint lives under the /api/v1/ prefix on your EmailFlow AI host. The current major version is v1; new endpoints are added without breaking existing ones, and any breaking change would ship as a new version alongside v1.

https://emailflow.ai/api/v1/<resource>

dns

Replace emailflow.ai with your own hostname on a self-hosted install (for example a local development server at http://127.0.0.1:8000/api/v1/). The examples in this section use the hosted base URL.

smart_toy

Machine-readable contracts: the full OpenAPI 3.1 specification (also as YAML), a concise agent guide at /llms.txt, and the complete docs corpus at /llms-full.txt.

Quick start

Create an API key under Account → API (the plaintext efa_ key is shown once — copy it immediately), then make your first call:

# Verify the key
curl https://emailflow.ai/api/v1/me \
  -H "Authorization: Bearer efa_YOUR_KEY"

# List your mailing lists
curl https://emailflow.ai/api/v1/lists \
  -H "Authorization: Bearer efa_YOUR_KEY"

Keys carry scopes — grant each integration only what it needs. The pre-platform account-wide token also keeps working; see the legacy token.

What's in this section

Page	Covers
Auth & API keys	Scoped `efa_` keys, the scope table, the legacy token, identity endpoints, credential safety.
Errors	The uniform error envelope, the closed code catalog, and how to handle each case.
Idempotency & rate limits	Safe retries with `Idempotency-Key`; per-key rate limits and the standard headers.
Resource reference	Lists, subscribers (single + bulk), segments, campaigns & logs, domains, templates, brand, usage, analytics events, notifications.
AI generation API	Generate and revise complete HTML emails from natural language — builder-compatible, brand-aware.
Automations API	The canonical flow graph format, CRUD, AI composition, and per-contact runs.
Webhooks	Signed event deliveries: the event catalog, signature verification, retries, auto-disable.
SDK, OpenAPI & llms.txt	The TypeScript SDK, the OpenAPI 3.1 document, and plain-text guides for AI agents.

Requests, responses, and status codes

Send parameters as form fields or, where noted, a JSON body. Every response is JSON. Status codes follow REST conventions — the canonical statuses returned to scoped efa_ keys:

Code	Meaning
200 OK	Successful read, update, or action.
201 Created	Resource created.
202 Accepted	Work queued (for example an asynchronous bulk import).
400 / 422	Malformed request / failed validation — details in the error envelope.
401 Unauthorized	Missing, invalid, revoked, or expired credential.
402 Payment required	Plan quota reached or AI credits exhausted.
403 Forbidden	Credential valid, but the key lacks the required scope.
404 Not Found	The requested resource does not exist (or belongs to another account).
409 Conflict	Resource state forbids the operation, or an idempotency conflict.
429 Too many requests	Rate limit exceeded — wait `Retry-After` seconds.
500 Server error	Something went wrong on the server.

Legacy-token callers keep their original pre-platform status codes and body shapes — see the envelope for how the two coexist.

Pagination. Index endpoints accept page and per_page (defaults vary by resource — 10 for lists and campaigns, 25 for subscribers). The analytics event feed uses cursor pagination instead (meta.next_cursor). The SDK abstracts both behind async iterators.

Usage analytics

Every API request is measured automatically — no setup required. Under Account → API → API usage you get request volume per day, error rate, and p50/p95 latency for your traffic, switchable between 7-day and 30-day windows, plus tables breaking the same window down per API key (legacy-token traffic shows as “Legacy token”) and per route.

The API usage dashboard on the Account API page: a requests-per-day bar chart with an error-rate line, a latency chart with p50 and p95 series, a 7-day or 30-day range picker, and breakdown tables per API key and per route — Account → API → API usage — volume, error rate, and latency for your integrations.

Only the route template (for example /api/v1/lists/{uid}) is recorded — never the actual identifiers or emails in your request paths — and raw per-request analytics are retained for 30 days, after which only daily aggregates remain.

Frequently asked questions

Do I need the API to use EmailFlow AI? No — everything works from the app. The API is for teams who want to connect their own apps and systems and automate data flow.

Which credential should I use? Scoped efa_ keys, passed in the Authorization: Bearer header — one key per integration. The legacy account token (including its ?api_token= query parameter) still works for existing clients but grants full access and may appear in logs.

How do I keep my keys safe? Treat API keys like passwords: store them as secrets, never commit them to code or client-side bundles, use a separate key per integration, and revoke any key that is ever exposed from Account → API.

Are there rate limits? Yes — per-minute limits by operation class, with an independent bucket per API key. See rate limits for the full matrix and headers. Your account's send and storage quotas apply on top — see plans and quotas.

Can my AI coding agent use this? Yes — point it at /llms.txt for a compact, always-current API guide, or the OpenAPI spec for exact schemas. See llms.txt.