Skip to content

Events ​

Things that happen in your own product. Post one and whatever automation is waiting for it starts, for that person.

This is the outbound direction only — your code telling Mailroom. For Mailroom telling your code about mail, see Webhooks.

Post an event ​

POST /api/v1/events

Scope: events:write

json
{
  "event": "trial.ended",
  "email": "person@example.com",
  "name": "Pat Doe",
  "fields": { "plan": "pro", "order": "A-19" },
  "consent_source": "signed up at checkout"
}
Field
eventrequiredThe name. Lowercased and tidied, so Trial.Ended and trial.ended are the same event
emailrequiredWho it happened to
nameoptionalUsed only if they have to be added to the list
fieldsoptionalMerged onto the person before the flow starts
consent_sourceoptionalWhere consent came from. Only used when they are not on the list yet

The reply names every automation that heard it, and what happened to that person in each:

json
{
  "event": "trial.ended",
  "declared": true,
  "matched": 1,
  "automations": [
    { "id": "aut_…", "name": "After the trial", "status": "started" }
  ]
}
statusMeaning
startedThey are at the top of the flow
restartedThey had finished it before; they are back at the top
already_runningThey are part-way through it, so nothing was done
skippedNothing happened. reason says why

The same reply carries stopped: flows this event ended, because it was what they were for.

json
{ "stopped": [{ "id": "aut_…", "name": "Cart recovery" }] }

And resumed: flows where this person was sitting on a Wait for an event box for this name. They move on down its arrived side straight away.

json
{ "resumed": [{ "id": "aut_…", "name": "After checkout" }] }

An event can do all three — starting one flow, ending another and waking a third — which is exactly what order.placed does.

matched: 0 means nothing was listening — no automation is switched on for that name. The event is still recorded.

An address nobody knows is skipped, not added

An event carrying an email is not that person asking for mail. Without consent_source an unknown address comes back as skipped. With it they are added to the automation's list first — the same consent record the subscribe endpoint requires — and the flow starts.

On a double opt-in list they are added as pending and nothing runs until they confirm.

fields are merged, not replaced: an event about one thing does not wipe what is already known about that person.

List the event names ​

GET /api/v1/events

Scope: events:read

json
{
  "data": [
    {
      "id": "evt_…",
      "name": "trial.ended",
      "description": "Posted by the billing worker the night a free trial runs out",
      "declared": true,
      "seen_count": 412,
      "last_seen_at": "2026-09-23T09:58:02.000Z",
      "automations": 2,
      "live_automations": 1
    }
  ]
}

declared is false for a name that arrived from the API before anybody wrote it down under Campaigns → Events. Those are worth looking at: a mistyped event name is otherwise invisible, and it looks exactly like nothing having happened.

Released under the MIT Licence.