# Glossary

Every term you'll meet in Mimeo and these docs — what it means, how Mimeo thinks about it, and where to read the whole story.

## Your Mimeo setup

**Mimeo (your instance).** When these docs say "Mimeo," they mean yours: your own instance of the Mimeo app, holding only your data — single-tenant, no shared platform behind it. Hosted, your Mimeo lives at `your-account-name.mimeoapp.com`; self-hosted, it lives on whatever domain you put it on. Everything else in this glossary lives in or talks to it.

**Web UI.** The admin app you log into at your Mimeo. Full parity with the agent surfaces — anything an agent can do, you can do by hand.

**Manager repo.** The git repo on your machine holding your whole email operation as files, synced with your Mimeo by the CLI. Cloned once from the Mimeo template; yours forever.

**Definition files.** The files in the manager repo — flows, segments, guards, sequences, emails, templates, `fields.yml`, `products.yml`, `settings.yml`. "Definitions" is the authored half of your data; runtime history is never a file.

**CLI (`mimeo`).** The single-file command line at `bin/mimeo` in the manager repo. Five commands — `init`, `auth`, `pull`, `diff`, `push` — all HTTPS calls to your Mimeo. It never touches git.

**MCP server.** A Model Context Protocol endpoint at `/mcp` on your Mimeo, giving a coding agent nearly the whole app as tools — authoring included, best used for questions and commit-less changes. Runs on your Mimeo itself; nothing to install locally.

**HTTP API.** The JSON API under `/api/v1` that every surface — web UI aside — goes through: events in and back out, full CRUD on everything authored, read-only reporting.

**API token.** A bearer credential (starts with `mm_`) created under **Settings → Agents & API**. One token authenticates the API, the CLI and the MCP server alike; it's shown once at creation and revocable any time.

**Skills.** Task recipes in the manager repo's `.claude/skills/` that teach your agent Mimeo's recurring jobs — building a flow, drafting an email, auditing account state.

**Sending provider.** The service that puts your mail on the wire — Postmark or Resend. Mimeo authors, personalizes, schedules and tracks; the provider delivers.

**Adapter.** The per-provider code inside Mimeo that translates "send this" and "what happened?" into one provider's API. One provider is active at a time, and you can write your own.

**Webhook.** How your provider reports back — deliveries, bounces, complaints — as signed HTTP posts to your Mimeo. Set up once in the sending wizard.

**Setup wizard.** The four-step first-run flow at `/setup`: pick a provider, connect it, name your senders, verify your domains — ending with the manager repo handoff.

## Sending & deliverability

**Sender.** A name-and-address pair your email comes from ("Ada Lovelace <ada@example.com>"). Defined once, picked per email.

**Sending domain.** A domain your senders' addresses live on, verified at the provider (so it may sign your mail) and connected to Mimeo with one CNAME.

**Link host.** The subdomain on your sending domain (like `mimeo.example.com`) that tracking and unsubscribe links ride, so subscriber-facing URLs stay on your domain. The CNAME from the wizard is what creates it.

**DKIM / SPF.** DNS records, set up at your provider, that let receiving inboxes verify your mail really came from you. The provider's dashboard walks you through them; Mimeo checks the result.

**Open tracking.** A one-pixel image per email that registers when loaded. Directional, not gospel — inbox privacy proxies inflate and undercount it.

**Click tracking.** Links rewritten through your link host so a click registers, then redirects on. Bot clicks are filtered.

**Unsubscribe.** A person opting out. Every email carries `{{ unsubscribe_url }}`; unsubscribed people stay on the books (so you don't re-import them) but nothing automated will mail them.

**Mailing address.** The physical postal address anti-spam law requires every marketing email to show. Set once in settings; layout footers show it via `{{ mailing_address }}`.

**One-click unsubscribe.** The `List-Unsubscribe` email header Gmail and Yahoo require of bulk senders — lets an inbox unsubscribe someone without a page visit. Mimeo sends it on every marketing email automatically.

**Bounce.** Mail that couldn't be delivered. Hard bounces (the address doesn't exist) suppress the person; soft bounces (full mailbox, greylisting) are transient.

**Complaint.** A recipient marked your mail as spam. Providers report it by webhook and Mimeo stops mailing that person. Complaint rate is the number to watch when migrating a list.

**Suppression.** The umbrella for "will not be mailed": unsubscribes, hard bounces, complaints. Enforced at send time by a built-in guard, so even a mis-built segment can't mail a suppressed person.

**Warm-up.** Starting a new domain or provider at low volume to your most engaged people and ramping up gradually, so inbox providers learn to trust you.

**Send window.** A settings-defined span of hours in which automated mail may go out, so a 3am trigger becomes a 9am send.

**Message stream (Postmark).** Postmark's separation of transactional from broadcast traffic. Your newsletters ride the Broadcasts stream; the wizard configures it.

## Working in Mimeo

**Person.** A subscriber: email address, name, custom fields, tags, and a timeline of everything that ever happened to them. Matched by lowercased email.

**Event.** A named fact about a person (`signed_up`, `order_completed`) POSTed to the API. Events create and update people, trigger flows, and build the timeline — they're the main way data enters Mimeo.

**Activity.** The instance-wide event feed under **Events → Activity** — every event, newest first, with its full payload one click away.

**Event registry.** One row per event name your Mimeo has ever seen — self-registered on first ingest, carrying occurrence counts, sources, seen window, the merged payload shape, and what listens for the name. Readable in the UI, the API and over MCP.

**Custom field.** A declared, typed attribute on people (plan, company). Declared under **Settings → Fields**; unknown keys sent to the API are ignored rather than becoming junk columns.

**Tag.** A freeform label on a person — the lightweight alternative to a field, useful in segment rules.

**Segment.** A live, rule-based audience ("plan is pro, opened something in 90 days"). Membership is evaluated when used, never frozen.

**Email.** A piece of content in the library: a **title** you call it by, a **subject** recipients read, and a markdown body with Liquid personalization, rendered in a layout. Leave the title blank and the subject stands in. Attached to steps and broadcasts as either the **shared** library row (edit once, changes every use) or an independent **copy** — a distinction Mimeo asks you to make explicitly.

**Template (layout / component).** The HTML/CSS shell an email renders inside (layout) and the reusable fragments it can pull in (components). A layout's CSS is yours to write, but it names a theme's values rather than quoting hex codes.

**Theme.** The creative decisions emails are built from: the colours — each with a light and a dark value — the font stacks, and the shape of the page. Layouts refer to them as `{{ theme.… }}` tags, so a brand colour lives in one place and changing it rebuilds every email on the theme, drafts included. One theme is the default, and a layout that doesn't pick one follows it. Under **Emails → Templates → Themes**.

**Snippet.** A saved bit of markdown you can drop into any email body.

**Broadcast.** A one-time send to an audience at a moment — a newsletter, an announcement. Broadcasts are runtime, not authored files: they carry a send time and a resolved audience.

**Sequence.** An ordered series of emails with delays — a welcome series, a course. People enter it (usually from a flow) and walk the steps.

**Flow.** Event-triggered automation: when this happens, do these steps — send, wait, branch, tag, enter a sequence. Defined as a single JSON document.

**Node (step).** One unit inside a flow. Each carries a permanent `id` that running people literally stand on — which is why ids are never renumbered or reused.

**Guard.** A send-time checkpoint — a condition checked the moment an email would actually go, able to hold, skip, cancel or exit. The built-in suppression guard is one.

**Run.** One person's live progress through one flow or sequence — where they're standing, what's next.

**Scheduled queue.** Every email that's due to go out, with status and due time — the answer to "what's about to send?" and "why didn't it?".

**Product.** A declared key for something you sell, so money events and purchase conditions speak the same names.

**Timeline.** The per-person ledger of everything — events, sends, opens, clicks, subscription changes, money. The place to answer "what actually happened to this person?"

**Watchdog.** A should-be-empty segment that raises a flag when anyone appears in it — a tripwire for states that should never happen.