Getting started

Seven steps from an empty instance to a real email in your inbox. Do them in order — each one depends on the last.

1. Log in to your instance

Mimeo is single-tenant: your install lives at your own domain and nobody else's data is in it. Log in with the credentials from your provisioning email. Everything below happens inside that instance, and every URL in these docs is relative to it.

2. Connect a sending provider

Mimeo holds your people, your content, and your history, but it doesn't put mail on the wire. A sending provider does that. Go to Settings → Provider, choose your provider — Bento, Postmark or Resend — and enter its credentials (for Bento: Site UUID, publishable key, and secret key). Credentials are encrypted at rest in your instance database.

Click Verify connection. Mimeo makes a live call to confirm the credentials work before it lets you rely on them. Then assign the provider the one-off sending duty — that's the switch that says "this connection is the one that sends."

Full walkthroughs, including what each provider can and can't do: Bento setup · Postmark setup · Resend setup.

3. Get your people in

There are two ways in, and most installs use both.

Import a CSV if you're migrating from another tool or starting from a list you already have. Mimeo accepts any CSV with a header row and lets you map each column yourself — including mapping a column to "already unsubscribed" so a migration doesn't email people who already opted out. See CSV import.

POST events for everything ongoing. Your app, your checkout, your signup form, and your agent all talk to the same endpoint:

curl -X POST https://your-instance.com/api/v1/events \
  -H "Authorization: Bearer mm_your_token" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "name": "signed_up",
    "person": { "first_name": "Ada" }
  }'

That single call creates the person if they're new, matches them on lowercased email if they're not, records first-touch attribution, and appends to their timeline. Create the API token first under Settings → API — it's shown once, so copy it then. Details: the event contract.

4. Define your custom fields

Custom fields are declared, not free-form. Go to Settings → Fields and add the ones your business actually uses — plan, company, signup source, whatever you'd want to filter or personalize on. Each has a key, a label, a type, and optionally a set of options and a description.

Declaring them up front matters for two reasons: unknown field keys sent to the API are ignored rather than silently creating junk columns, and your coding agent can read the schema back with GET /api/v1/field_definitions so it knows what this install understands without you telling it.

5. Author an email

Go to Emails and create one. You write in markdown, and you can personalize with Liquid:

Hi {{ person.first_name | default: "there" }},

Thanks for joining. You're on the {{ person.fields.plan }} plan.

Emails render inside a layout — the HTML shell that carries your branding and your footer. One layout is marked default, and your footer should include {{ unsubscribe_url }} so every message has a working opt-out. Buttons, reusable components, and image hosting are all covered in Emails.

6. Preview it against real data

Preview renders your email as a specific person sees it — pick a saved preview person, pull a random one, or search for someone by email. Check it at mobile and desktop widths and in both light and dark, because your readers aren't all on the same setup.

This is where Liquid mistakes surface. A missing | default: shows up as a blank space in a real render long before it shows up in a complaint.

7. Send a test to yourself

Use Send test to me. This is the end-to-end check: it runs the real compile, hands the real message to your real provider, and delivers to your real inbox. If your provider credentials are wrong or your layout is broken, you find out here.

Open it and confirm three things:

• The content and personalization look right.
• The unsubscribe link in the footer works.
• The open registers and a link click registers — check the person's timeline afterward.

Then check the timeline

Go to People, open yourself, and look at the timeline. You should see the event that created you, the send, the open, and the click, in order. That timeline is the thing you'll come back to most — it's the answer to "what actually happened to this person?"