Automations API

Endpoints

GET   /automations
POST  /automations
GET   /automations/:id
PATCH /automations/:id
POST  /automations/:id/run

Reads require automations:read. Creation, updates, and manual runs require automations:write. POST and PATCH support an Idempotency-Key header. List returns up to the 100 most recently updated automations.

Create a daily brief

{
  "name": "Daily brief",
  "definition": {
    "trigger": {
      "type": "scheduled",
      "cron": "0 8 * * *",
      "time_zone": "Europe/Lisbon"
    },
    "conditions": [],
    "actions": [{
      "type": "generate_mail_report",
      "metric": "received",
      "lookback_minutes": 1440
    }],
    "mode": "draft",
    "scope": {
      "mailbox_ids": ["mbx_sales", "mbx_support", "mbx_personal"],
      "calendar_addresses": []
    }
  }
}

Creating saves version 1 and activates it in one transaction. If validation or activation fails, nothing is saved. A scheduled cron expression can only name one daily or weekly time.

Definitions and safety

• Triggers: email_received, scheduled, manual, or thread_state.
• Conditions use trusted message metadata or a positive semantic match with an explicit confidence threshold.
• Draft mode is the default and the safe choice. Send mode allows only one deterministic reply on an incoming-email trigger, and the organization's sending policy still applies.
• For a plain move, archive, read or star, use inbox rules. Reach for an automation only when you need a semantic or time-based condition.

Update and version

{
  "status": "paused"
}

Status-only updates accept active, paused, or disabled. Changing the name or definition creates a new immutable version and activates it in one step. There is no DELETE endpoint. Disable an automation to stop it running.

Ownership and mailbox constraints

Each automation belongs to a person. An API key manages the automations of the active member who created the key. Shipmail checks the key's mailbox constraints on every request and hides an automation unless the key allows every mailbox it covers. A key with no active member as owner cannot manage automations.