API overview

The HTTP interface to your instance. 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 instance is the API — the base URL is your own domain:

https://your-instance.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 → 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 — 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 in v1

Tokens have full access. There is no scoping or permissioning yet. Treat every token as equivalent to full control of the instance: 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 exist so you can build your own unsubscribe page, and that page 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/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
`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`, `/sequences`, `/tags`, `/products`, `/queue`	Read-only lookups so a flow definition can reference real records
`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 instance, read the event contract first. Practically everything that gets data into Mimeo goes through that one endpoint.