Events

Send custom events into Groundmail to trigger transactional automations.

Base URL: https://api.groundmail.dev

Authentication

Authorization: Bearer gm_…

Dashboard session cookies also work for browser requests to /api/events, which is how the automations canvas editor sends test events.

Trigger an event

POST /events

{
  "name": "user.created",
  "user_id": "user_123",
  "email": "user@example.com",
  "data": {
    "name": "Ada Lovelace",
    "plan": "pro"
  }
}

type is accepted as an alias for name.

Idempotency

Use Idempotency-Key for replay-safe retries:

Idempotency-Key: evt_user_created_123

Retries with the same key and body return the original response. Reusing the key with a different body returns HTTP 409.

202 Accepted

{
  "event": {
    "id": "ae_123",
    "name": "user.created",
    "user_id": "user_123",
    "email": "user@example.com",
    "data": {
      "name": "Ada Lovelace",
      "plan": "pro"
    },
    "source": "api",
    "created_at": "2026-07-26T12:00:00.000Z"
  },
  "matched_automations": 2,
  "resumed_runs": 1,
  "cancelled_runs": 0
}

matched_automations = active automations whose trigger matched this event
resumed_runs = waiting runs resumed by this event (wait_for_event)
cancelled_runs = active runs cancelled because this event matched trigger.cancel_on_events

Event shape

Field	Type	Notes
`name`	string	Required unless `type` is provided
`type`	string	Alias for `name`
`user_id`	string	Optional identity hint for wait/resume matching
`email`	string	Optional identity hint for wait/resume matching
`data`	object	Optional event payload used by conditions and email templates
`dry_run`	boolean	Dashboard only — with `automation_id`, runs that one automation even if draft/paused; skips delays/waits and stubs email/SMS
`automation_id`	string	Required with `dry_run`; rejected on API-key requests

Inside automations, you can reference:

{{event.name}}
{{event.email}}
{{event.user_id}}
{{event.data.foo}}

Typical flow

Create an automation (dashboard canvas, POST /automations, or groundmail automations create) with trigger user.created
Activate it (POST /automations/{id} with { "action": "activate" })
Send POST /events from your app when that business event happens
Groundmail queues the run in Bull/Redis
Send-email steps flow through the same transactional send path as POST /emails

SDK

import { Groundmail } from 'groundmail'

const client = new Groundmail(process.env.GROUNDMAIL_API_KEY!)

await client.events.trigger({
  name: 'user.created',
  user_id: 'user_123',
  email: 'user@example.com',
  data: { name: 'Ada Lovelace' },
  idempotencyKey: 'evt_user_created_123',
})

CLI

GROUNDMAIL_API_KEY=$GROUNDMAIL_API_KEY npx -y --package=groundmail-cli -- groundmail events send \
  --name user.created \
  --email user@example.com \
  --user-id user_123 \
  --data '{"name":"Ada Lovelace"}'

OpenAPI

Machine-readable spec: openapi/groundmail.yaml