API overview

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.

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.

No scopes

Tokens have full access. There is no scoping or permissioning. Treat every token as equivalent to full control of your Mimeo: keep them in your secret manager, never in client-side code, and issue separate named tokens per integration so you can revoke one without breaking the rest.

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 — additionally report per-item outcomes in the response body, so a batch can partially succeed.

The public exception

The subscription-management endpoints 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 — signups, opt-ins, purchases, payments, subscriptions
`GET /api/v1/events`	The event feed — everything that happened, newest first, filterable by name, source, person and time window
`GET /api/v1/event_types`	The event registry — 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
`GET /api/v1/people/:id_or_email`	Read one person, including fields, tags, attribution, and lifetime spend
`POST /api/v1/people/:id_or_email/unsubscribe` `POST /api/v1/people/:id_or_email/resubscribe`	Unsubscribe or resubscribe someone as the operator — the person page's buttons, for agents
`POST /api/v1/imports` and friends	CSV import — 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 — full parity with the UI
`GET /api/v1/segments` and friends	Create, check, count and read segments by key — full parity with the UI
`GET /api/v1/emails` and friends	The email library — CRUD, the shared-vs-copy contract, and `fork`
`GET /api/v1/media` and friends	The media library — multipart upload, alt text, and deletion
`GET /api/v1/templates` and friends	Layouts and components — the HTML and CSS an email is dressed in, plus the default layout
`GET /api/v1/themes` and friends	Themes — the colors, fonts and page shape a layout is built from
`GET /api/v1/sequences` and friends	Sequences and their steps — full parity with the UI
`GET /api/v1/broadcasts` and friends	Broadcasts — compose, schedule, send now, cancel
`GET /api/v1/guards` and friends	Send-time guards — create, toggle, scope
`GET /api/v1/definitions`, `POST …/diff`, `POST …/apply`	Everything you author, as files — the three calls the CLI wraps
`GET /api/v1/settings` and `PATCH`	The writable 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 so a flow definition can reference real records
`POST /webhooks/email/:provider`	Inbound provider webhooks — deliveries, bounces, complaints (verified per adapter)
`GET /api/v1/subscription/:token`	Subscription status (public)
`POST /api/v1/subscription/:token/unsubscribe`	Unsubscribe (public)
`POST /api/v1/subscription/:token/resubscribe`	Resubscribe (public)
`POST /u/:token`	RFC 8058 one-click unsubscribe (public, called by mail clients)
`GET /o/:token`, `GET /l/:token`	Open pixel and link redirect — 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 first. Practically everything that gets data into Mimeo goes through that one endpoint.