# API overview

Authenticate against your Mimeo with a bearer token, and learn the conventions shared by every endpoint: base URL, JSON errors, and public exceptions.

The HTTP interface to your Mimeo. This is how your application, your checkout, and your coding agent put data into Mimeo and read it back.

## Base URL

There is no shared Mimeo API host. Your Mimeo is the API — the base URL is your own domain:

```
https://your-mimeo.com/api/v1/…
```

Every path in these docs is relative to that. Single-tenant means your data never travels through anyone else's infrastructure to reach you.

## Authentication

Authenticated endpoints take a bearer token in the `Authorization` header:

```
Authorization: Bearer mm_your_token_here
```

Tokens start with the `mm_` prefix, which makes them easy to spot in logs and secret scanners.

### Creating a token

In the app, go to **Settings → Agents & API** and create one. You give it a name so you can tell your agent's token from your checkout's token later.

> [!CAUTION]
> **The token is shown once.** Copy it when it's created — your Mimeo stores it hashed and cannot show it to you again. If you lose it, revoke it and make a new one.

Every token can be **revoked** at any time, and each one shows its **last used** time so you can spot tokens that are no longer needed or being used from somewhere you didn't expect.

### Operator and source-bound tokens

Unscoped operator tokens have **full access**, including MCP. A token bound to a `source_app` has only the integration surface: minimal email lookup and rename (`GET` and `PATCH /api/v1/people/email`), [email activity](https://mimeohq.com/docs/api/people#email-activity), event intake (`POST /api/v1/events`), silent subscription reconciliation (`POST /api/v1/subscription_reconciliations`), and subscription versions (`GET /api/v1/subscription_versions`). Other endpoints, including rich person reads and MCP, return `403 {"error":"forbidden"}` for source-bound tokens.

A source binding restricts actions, not ownership of people or their email history. Keep every token in your secret manager, never in client-side code, and authorize lookups in your calling app. Issue separate named tokens per integration so you can revoke one without breaking the rest. No token change is needed to use email activity with an existing source-bound token.

## Requests and responses

Send JSON, get JSON. Include `Content-Type: application/json` on requests with a body.

### Errors

Errors come back in a consistent shape:

```
{ "error": "Invalid or missing API token" }
```

The HTTP status carries the category and the `error` string explains the specifics. Endpoints that process multiple items at once — notably [events](https://mimeohq.com/docs/api/events) — additionally report per-item outcomes in the response body, so a batch can partially succeed.

## The public exception

The [subscription-management endpoints](https://mimeohq.com/docs/api/subscriptions) are the one part of the API that does **not** use a bearer token. They're public, and authenticated by the signed token in the URL itself.

That's deliberate. Those endpoints are what Mimeo's own unsubscribe page is built on, and what your own page calls if you'd rather host one — and a page like that runs in your subscribers' browsers, where an API token could never safely go.

## The endpoints

| Endpoint | Purpose |
| --- | --- |
| `POST /api/v1/events` | [Everything that happens](https://mimeohq.com/docs/api/events) — signups, opt-ins, purchases, payments, subscriptions |
| `GET /api/v1/events` | [The event feed](https://mimeohq.com/docs/api/events#reading-events) — everything that happened, newest first, filterable by name, source, person and time window |
| `GET /api/v1/event_types` | [The event registry](https://mimeohq.com/docs/api/events#event-types) — every name this instance has seen, with counts, payload shapes and what listens for each |
| `GET /api/v1/field_definitions` | [Discover this install's custom-field schema](https://mimeohq.com/docs/api/events#field-definitions) |
| `GET /api/v1/people/:id_or_email` | [Read one person](https://mimeohq.com/docs/api/events#read-a-person), including fields, tags, attribution, and lifetime spend |
| `GET /api/v1/people/email/activity` | [One person's sent emails and human opens/clicks](https://mimeohq.com/docs/api/people#email-activity) — also available to source-bound tokens |
| `POST /api/v1/people/:id_or_email/unsubscribe`<br>`POST /api/v1/people/:id_or_email/resubscribe` | [Unsubscribe or resubscribe someone as the operator](https://mimeohq.com/docs/api/people#unsubscribe) — the person page's buttons, for agents |
| `POST /api/v1/imports` and friends | [CSV import](https://mimeohq.com/docs/api/imports) — upload, map columns, preview, commit, and poll for the report; full parity with the UI wizard |
| `GET /api/v1/flows` and friends | [Build, validate, dry-run and activate flows](https://mimeohq.com/docs/api/flows) — full parity with the UI |
| `GET /api/v1/segments` and friends | [Create, check, count and read segments](https://mimeohq.com/docs/api/segments) by key — full parity with the UI |
| `GET /api/v1/emails` and friends | [The email library](https://mimeohq.com/docs/api/emails) — CRUD, the shared-vs-copy contract, and `fork` |
| `GET /api/v1/media` and friends | [The media library](https://mimeohq.com/docs/api/media) — multipart upload, alt text, and deletion |
| `GET /api/v1/templates` and friends | [Layouts and components](https://mimeohq.com/docs/api/templates) — the HTML and CSS an email is dressed in, plus the default layout |
| `GET /api/v1/themes` and friends | [Themes](https://mimeohq.com/docs/api/themes) — the colors, fonts and page shape a layout is built from |
| `GET /api/v1/sequences` and friends | [Sequences and their steps](https://mimeohq.com/docs/api/sequences) — full parity with the UI |
| `GET /api/v1/broadcasts` and friends | [Broadcasts](https://mimeohq.com/docs/api/broadcasts) — compose, schedule, send now, cancel |
| `GET /api/v1/guards` and friends | [Send-time guards](https://mimeohq.com/docs/api/guards) — create, toggle, scope |
| `GET /api/v1/definitions`, `POST …/diff`, `POST …/apply` | [Everything you author, as files](https://mimeohq.com/docs/api/definitions) — the three calls the CLI wraps |
| `GET /api/v1/settings` and `PATCH` | [The writable settings](https://mimeohq.com/docs/api/settings) — tunables, send windows, brand |
| `GET /api/v1/reporting/…` | Read-only reporting for emails, sequences, flows and broadcasts — the same numbers as the UI pages, including delivered, bounced (hard/soft), complaint and suppression counts |
| `GET /api/v1/tags`, `/products`, `/queue` | [Read-only lookups](https://mimeohq.com/docs/api/flows#lookups) so a flow definition can reference real records |
| `POST /webhooks/email/:provider` | [Inbound provider webhooks](https://mimeohq.com/docs/api/webhooks) — deliveries, bounces, complaints (verified per adapter) |
| `GET /api/v1/subscription/:token` | [Subscription status](https://mimeohq.com/docs/api/subscriptions) (public) |
| `POST /api/v1/subscription/:token/unsubscribe` | [Unsubscribe](https://mimeohq.com/docs/api/subscriptions) (public) |
| `POST /api/v1/subscription/:token/resubscribe` | [Resubscribe](https://mimeohq.com/docs/api/subscriptions) (public) |
| `POST /u/:token` | [RFC 8058 one-click unsubscribe](https://mimeohq.com/docs/api/subscriptions#one-click) (public, called by mail clients) |
| `GET /o/:token`, `GET /l/:token` | [Open pixel and link redirect](https://mimeohq.com/docs/api/tracking) — Mimeo generates these; you never call them directly |

## Start here

If you're wiring up an integration or pointing an agent at your Mimeo, read [the event contract](https://mimeohq.com/docs/api/events) first. Practically everything that gets data into Mimeo goes through that one endpoint.