The Black Friday sale: $100 off Mimeo. Buy now →
Docs menu Event contract

Event contract

This page is written for AI agents. People ask their agent to do the work; see How it fits together.

Events are the trigger stream — the one way the outside world tells Mimeo that something happened. Event-triggered flows start here; renewal and ending flows start from subscription dates and inactivity flows from a stretch without opens or clicks instead, without a new event type.

An event is a name, a person, and whatever details you want to carry. There is no schema and there never will be: your app's vocabulary is your data, not our product vocabulary.

POST /api/v1/events
Authorization: Bearer mm_your_token
Content-Type: application/json

{
  "email": "ada@example.com",
  "name": "signed_up",
  "details": { "plan": "trial", "source": "ads" },
  "occurred_at": "2026-07-29T10:00:00Z"
}

The fields

Field Notes
email Required. The universal key — lowercased, and the person is created if they're new.
name Required. Your own vocabulary. Triggers match on it exactly. One name is reserved: internal_note is refused here — internal notes go through the notes endpoint, which never triggers automation.
details Any JSON object. Trigger matches and event_occurred conditions read these.
occurred_at Optional. Defaults to now. Timeline ordering.
idempotency_key Optional. A repeat of the same key is recognised as a duplicate and does nothing, which makes an at-least-once sender safe.
person Optional. first_name, last_name, fields, tags — upserted alongside the event.
attribution Optional, first touch only: landing page, referrer, UTMs, device, country.

Batching

Send up to 100 at once as { "events": [ … ] }. The response carries a per-event result, so a partial failure tells you exactly which ones.

{ "results": [
    { "status": "created",   "person_id": 41, "event_id": 902 },
    { "status": "duplicate", "person_id": 41, "event_id": 887 },
    { "status": "invalid",   "error": "email is required" } ] }

Events Mimeo writes itself

Your events aren't the only ones in the stream. State changes fire events too, so a flow can trigger on them exactly as it would on yours:

Event When
tag_added · tag_removed A tag changes, by hand or by a flow. Details carry the tag. Renaming a tag fires neither, and updates the tag name in past ones.
field_changed A custom field changes. Details carry the key, the old value and the new one.
unsubscribed · resubscribed Suppression state changes. Details carry the reason and how it happened.
pruned A flow's prune step unsubscribed someone for inactivity, straight after its unsubscribed event. Details carry flow, flow_name, flow_run_id, inactive_since and days. Use it in event_occurred conditions and segments to tell pruning from choosing to leave.
flow_entered · flow_exited Someone enters or leaves a flow. Details carry the flow and run, and an exit carries its reason.
sequence_completed Someone reaches the end of a sequence.

A flow's fire_event step writes one too — which is how one flow hands off to another. The validator warns (self_trigger) if a flow fires the event that triggers itself.

Money is events

Purchases, subscriptions and payments are recorded from events with the right names and details — Mimeo has no direct connection to a payment processor, because your systems already know and one source of truth beats two. See People for the shapes.

What events are not

Opens and clicks are not events. They're telemetry, in their own tables, with bot filtering — deliberately not part of the trigger stream, because a flow branching on "opened" is a flow branching on a number that Apple Mail Privacy Protection inflates. Use the opened_email and clicked_email conditions if you want them, knowing that.

Every name registers itself

The first time a name arrives — from your systems, from the engine, or from an import — it registers itself in the event registry: one row per name, carrying its occurrence count, sources, first/last seen, and a merged shape of every payload ever sent under it. Nothing is declared ahead of time, so the registry is exactly what has actually happened — the live vocabulary triggers, gates and event_occurred conditions draw from. Read it in the UI under Events, over GET /api/v1/event_types, or with the MCP list_event_types tool — and describe_schema returns the names as event_names. The feed of individual occurrences is readable too: GET /api/v1/events.

Designing your event names

  • Name what happened, in the past tense, from the person's side: signed_up, started_trial, viewed_pricing.
  • Prefer one event with details over many near-identical names. plan_changed with { from, to } beats upgraded_to_pro, upgraded_to_team and the rest — a trigger match can narrow it, and you don't have to touch a flow when you add a plan.
  • Send an idempotency_key if your sender might retry. It stops a retry from being recorded twice.

See also: Events API · Flow schema

View as Markdown

Powerful email automation you fully control.

Buy now