GroundmailDocs

Automations

Create and manage event-driven transactional automations with a Bearer gm_… API key (or dashboard session).

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

You can also build flows visually in the dashboard canvas under Automations.

Authentication

Authorization: Bearer gm_…

Create an automation

POST /automations

Creates a draft. Activate it before events will match.

{
  "name": "Welcome email",
  "trigger": {
    "type": "event",
    "event": "user.created"
  },
  "steps": [
    {
      "type": "send_email",
      "email": {
        "from": "you@yourdomain.com",
        "to": "{{event.email}}",
        "subject": "Welcome",
        "html": "<p>Hi {{event.data.name}}</p>"
      }
    }
  ]
}

Examples below are generated from src/lib/dx/snippets.ts (same source as the dashboard).

curl

curl -X POST https://api.groundmail.dev/automations \
  -H "Authorization: Bearer gm_…" \
  -H "Content-Type: application/json" \
  -d '{"name":"Welcome email","trigger":{"type":"event","event":"user.created"},"steps":[{"type":"send_email","email":{"from":"you@yourdomain.com","to":"{{event.email}}","subject":"Welcome","html":"<p>Hi {{event.data.name}}</p>"}}]}'

npm

npm install groundmail

import { Groundmail } from 'groundmail'

const client = new Groundmail('gm_…')

const { automation } = await client.automations.create({
  name: 'Welcome email',
  trigger: { type: 'event', event: 'user.created' },
  steps: [
    {
      type: 'send_email',
      email: {
        from: 'you@yourdomain.com',
        to: '{{event.email}}',
        subject: 'Welcome',
        html: '<p>Hi {{event.data.name}}</p>',
      },
    },
  ],
})

await client.automations.activate(automation.id)

CLI

GROUNDMAIL_API_KEY=gm_… npx -y --package=groundmail-cli -- groundmail automations create --file ./welcome.json
GROUNDMAIL_API_KEY=gm_… npx -y --package=groundmail-cli -- groundmail automations activate --id "$AUTOMATION_ID"

welcome.json should match the request body above.

Endpoints

Method Path Notes
GET /automations List
POST /automations Create draft
GET /automations/{id} Get
PATCH /automations/{id} Update name/trigger/steps
DELETE /automations/{id} Delete
POST /automations/{id} { "action": "activate" | "pause" }
GET /automations/runs Optional ?automation_id=
GET /automations/runs/{id} Run detail
POST /automations/runs/{id} { "action": "cancel" | "retry" }

Step types

Type Purpose
send_email Send via the same transactional send path as POST /emails — inline subject/html or a published email.template
send_sms Send SMS via Twilio — requires a connected integration and sms.to + sms.body
delay Wait seconds before the next step
condition Continue only if true; false stops the run (not if/else branching)
wait_for_event Pause until another event arrives (optional timeout_seconds; on_timeout continue or fail, default fail)

Trigger options: cancel_on_events — array of event names that cancel active runs for the same recipient when fired.

Placeholders in email and SMS steps: {{event.email}}, {{event.user_id}}, {{event.data.foo}}.

SMS example (send_sms)

Connect Twilio first (integrations twilio connect), then create an automation:

{
  "name": "Auth OTP (SMS)",
  "trigger": { "type": "event", "event": "auth.code_requested" },
  "steps": [
    {
      "type": "send_sms",
      "sms": {
        "to": "{{event.data.phone}}",
        "body": "Your code is {{event.data.code}}. Expires in 10 min."
      }
    }
  ]
}
GROUNDMAIL_API_KEY=gm_… npx -y --package=groundmail-cli -- groundmail integrations twilio connect \
  --account-sid AC… --auth-token … --from +15551234567
GROUNDMAIL_API_KEY=gm_… npx -y --package=groundmail-cli -- groundmail automations create --file ./otp-sms.json
GROUNDMAIL_API_KEY=gm_… npx -y --package=groundmail-cli -- groundmail automations activate --id "$AUTOMATION_ID"

Template example (mutually exclusive with inline subject / html / text):

{
  "type": "send_email",
  "email": {
    "from": "you@yourdomain.com",
    "to": "{{event.email}}",
    "template": {
      "id": "welcome",
      "variables": { "name": "{{event.data.name}}" }
    }
  }
}

Trigger the flow

After activate, send events with POST /events or:

groundmail events send --name user.created --email user@example.com --data '{"name":"Ada"}'