groundmail-dev Automations API

openapi: 3.2.0
info:
  title: Groundmail Automations API
  version: 0.16.0
  description: 'Transactional email API for developers.

    Auth: `Authorization: Bearer gm_…` with an API key, or `Bearer gm_oat_…` with an OAuth

    access token from the device flow (`groundmail login`). Dashboard session cookies work

    for integrations.


    Azure managed identity (keyless): an Azure workload can send a Microsoft Entra access

    token (a JWT) as the Bearer credential instead of a key. Register the identity''s tenant

    ID, object ID and token audience in the dashboard (API keys → Azure managed identity);

    it then has the same access options as an API key (scopes, domain limit, tenant).

    App-only tokens only. Any authentication failure is the same 401 `unauthorized`.

    See https://docs.groundmail.dev/authentication/azure-managed-identity.


    Test mode: a test key (`gm_test_…`, `POST /api-keys` with `test: true`) behaves

    like a live key, but its sends are never delivered: they are stored with

    `test: true`, get simulated events and webhooks (`data.test: true`), and do not

    count toward plan limits, the sending ramp, stats or billing. Simulator

    addresses (`delivered@`, `bounce@`, `block@`, `complaint@`, `suppressed@`,

    `delayed@simulator.groundmail.dev`, plus addressing allowed) produce one outcome

    each with any key. See https://docs.groundmail.dev/testing.


    Tenants: a platform that sends email for its own customers creates one tenant per

    customer (`/tenants`), each with its own domains, suppression list, stats, sending

    ramp and pause switch. Name the tenant with `tenant` on sends, domains and

    suppressions, or send from a domain the tenant owns. API keys and webhook

    endpoints can be limited to tenants. Included on pay as you go and the Dedicated plan;

    elsewhere a request that names a tenant gets 403 `tenants_not_enabled`. See

    https://docs.groundmail.dev/tenants.


    Data retention: sent emails (content and events) and received emails are kept for

    your plan''s window, then deleted: 7 days on Free, 30 on Pro, 90 on Scale, up to 365

    on Dedicated. Past it, `GET /emails/{id}` and `GET /received-emails/{id}` return

    404 `not_found` and lists no longer include them. Aggregate stats

    (`GET /deliverability`) are kept. Store webhook events to keep history longer. See

    https://docs.groundmail.dev/emails#data-retention.


    Scopes: every credential carries scopes (`full`, `emails:send`, `emails:read`,

    `domains:read`, `domains:write`, `webhooks:write`, `templates:write`,

    `suppressions:write`, `account:read`). Each operation lists the scope it needs under

    `x-required-scope` (space-separated: all of them; `a | b`: either); a credential

    without it gets 403 `insufficient_scope` with `required_scope`. `full` grants everything; `domains:write` includes `domains:read`.

    Legacy `sending` API keys have `emails:send` + `emails:read`.

    Production base URL: https://api.groundmail.dev'
servers:
- url: https://api.groundmail.dev
  description: Production
tags:
- name: Automations
  description: Create and manage event-driven transactional automations
paths:
  /automations:
    get:
      operationId: listAutomations
      x-required-scope: full
      summary: List automations
      tags:
      - Automations
      security:
      - bearerAuth: []
      responses:
        '200':
          description: Automation list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListAutomationsResponse'
        '401':
          description: Missing or invalid API key / session
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    post:
      operationId: createAutomation
      x-required-scope: full
      summary: Create a draft automation
      tags:
      - Automations
      security:
      - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateAutomationRequest'
            examples:
              welcome:
                value:
                  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>
      responses:
        '201':
          description: Automation created as draft
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AutomationResponse'
        '400':
          description: Invalid automation definition
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing or invalid API key / session
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Automation name already in use
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /automations/{id}:
    get:
      operationId: getAutomation
      x-required-scope: full
      summary: Get an automation
      tags:
      - Automations
      security:
      - bearerAuth: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Automation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AutomationResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    patch:
      operationId: updateAutomation
      x-required-scope: full
      summary: Update an automation definition
      tags:
      - Automations
      security:
      - bearerAuth: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateAutomationRequest'
      responses:
        '200':
          description: Updated automation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AutomationResponse'
        '400':
          description: Invalid update
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Name conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    delete:
      operationId: deleteAutomation
      x-required-scope: full
      summary: Delete an automation
      tags:
      - Automations
      security:
      - bearerAuth: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Deleted
          content:
            application/json:
              schema:
                type: object
                required:
                - ok
                properties:
                  ok:
                    type: boolean
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    post:
      operationId: automationAction
      x-required-scope: full
      summary: Activate or pause an automation
      tags:
      - Automations
      security:
      - bearerAuth: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AutomationActionRequest'
      responses:
        '200':
          description: Updated automation status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AutomationResponse'
        '400':
          description: Invalid action
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /automations/runs:
    get:
      operationId: listAutomationRuns
      x-required-scope: full
      summary: List automation runs
      tags:
      - Automations
      security:
      - bearerAuth: []
      parameters:
      - name: automation_id
        in: query
        required: false
        schema:
          type: string
        description: Filter runs to a single automation
      responses:
        '200':
          description: Run list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListAutomationRunsResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /automations/runs/{id}:
    get:
      operationId: getAutomationRun
      x-required-scope: full
      summary: Get an automation run
      tags:
      - Automations
      security:
      - bearerAuth: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Run detail
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AutomationRunResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    post:
      operationId: automationRunAction
      x-required-scope: full
      summary: Cancel or retry an automation run
      tags:
      - Automations
      security:
      - bearerAuth: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AutomationRunActionRequest'
      responses:
        '200':
          description: Updated run
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AutomationRunResponse'
        '400':
          description: Invalid action
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    ListAutomationRunsResponse:
      type: object
      required:
      - runs
      properties:
        runs:
          type: array
          items:
            $ref: '#/components/schemas/AutomationRun'
    ListAutomationsResponse:
      type: object
      required:
      - automations
      properties:
        automations:
          type: array
          items:
            $ref: '#/components/schemas/Automation'
    AutomationRunActionRequest:
      type: object
      required:
      - action
      properties:
        action:
          type: string
          enum:
          - cancel
          - retry
    ErrorResponse:
      type: object
      required:
      - error
      properties:
        error:
          type: object
          required:
          - message
          properties:
            message:
              type: string
              description: What went wrong, in plain English. Wording can change; branch on `code`.
            code:
              $ref: '#/components/schemas/ErrorCode'
            hint:
              type: string
              description: 'How to fix the error. Specific to the failure when known (for example a sandbox recipient), otherwise the default for `code`.

                '
            docs_url:
              type: string
              format: uri
              description: Link to this code on the errors page, `https://docs.groundmail.dev/errors#<code>`.
              example: https://docs.groundmail.dev/errors#validation_error
            upgrade_url:
              type: string
              description: 'Dashboard path to upgrade when code is plan_limit or domain_limit. Absent for `daily_ramp_limit`, which upgrading does not lift.

                '
            required_scope:
              type: string
              description: 'With `insufficient_scope`: the scope (or space-separated scopes) the operation needs. Also sent as `WWW-Authenticate: Bearer error="insufficient_scope", scope="…"`.

                '
            details:
              description: 'Optional structured details. For send blocks this may include `suppressed` (global suppression list) or `category_unsubscribed` plus `category` and `email_id` (category opt-out). A `daily_ramp_limit` carries `stream` (`transactional` or `product`), `daily_limit` (today''s recipient limit for that stream), `used_today`, `recipients` (in this send), `ramp_stage` and `resets_at` (next 00:00 UTC, ISO 8601), plus `tenant` when the tenant''s own limit refused the send.

                '
    AutomationActionRequest:
      type: object
      required:
      - action
      properties:
        action:
          type: string
          enum:
          - activate
          - pause
    AutomationRunStep:
      type: object
      required:
      - id
      - step_index
      - step_type
      - status
      - output
      - error
      - started_at
      - completed_at
      - created_at
      - updated_at
      properties:
        id:
          type: string
        step_index:
          type: integer
        step_type:
          type: string
          enum:
          - delay
          - send_email
          - condition
          - wait_for_event
        status:
          type: string
          enum:
          - started
          - waiting
          - completed
          - failed
        output:
          nullable: true
        error:
          type: string
          nullable: true
        started_at:
          type: string
          format: date-time
        completed_at:
          type: string
          format: date-time
          nullable: true
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    AutomationRun:
      type: object
      required:
      - id
      - automation_id
      - trigger_event_id
      - status
      - current_step
      - waiting_for_event
      - wait_timeout_at
      - context
      - last_error
      - cancel_requested_at
      - started_at
      - completed_at
      - created_at
      - updated_at
      properties:
        id:
          type: string
        automation_id:
          type: string
        trigger_event_id:
          type: string
          nullable: true
        status:
          type: string
          enum:
          - queued
          - running
          - waiting
          - completed
          - failed
          - cancelled
        current_step:
          type: integer
        waiting_for_event:
          type: string
          nullable: true
        wait_timeout_at:
          type: string
          format: date-time
          nullable: true
        context:
          type: object
          additionalProperties: true
        last_error:
          type: string
          nullable: true
        cancel_requested_at:
          type: string
          format: date-time
          nullable: true
        started_at:
          type: string
          format: date-time
          nullable: true
        completed_at:
          type: string
          format: date-time
          nullable: true
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        automation:
          $ref: '#/components/schemas/Automation'
        trigger_event:
          $ref: '#/components/schemas/EventRecord'
        steps:
          type: array
          items:
            $ref: '#/components/schemas/AutomationRunStep'
          description: Present on run detail responses
    Automation:
      type: object
      required:
      - id
      - name
      - status
      - trigger
      - steps
      - folder
      - created_at
      - updated_at
      properties:
        id:
          type: string
        name:
          type: string
        status:
          type: string
          enum:
          - draft
          - active
          - paused
        trigger:
          $ref: '#/components/schemas/AutomationTrigger'
        steps:
          type: array
          items:
            $ref: '#/components/schemas/AutomationStep'
          minItems: 1
          maxItems: 20
        folder:
          type: string
          nullable: true
          description: Name of the dashboard folder it is filed in, or null.
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    CreateAutomationRequest:
      type: object
      required:
      - name
      - trigger
      - steps
      properties:
        name:
          type: string
        trigger:
          $ref: '#/components/schemas/AutomationTrigger'
        steps:
          type: array
          items:
            $ref: '#/components/schemas/AutomationStep'
          minItems: 1
          maxItems: 20
        folder:
          type: string
          maxLength: 64
          description: Folder to file it in on the dashboard, matched by name (any case) and created when it does not exist.
    AutomationRunResponse:
      type: object
      required:
      - run
      properties:
        run:
          $ref: '#/components/schemas/AutomationRun'
    AutomationResponse:
      type: object
      required:
      - automation
      properties:
        automation:
          $ref: '#/components/schemas/Automation'
        warnings:
          type: array
          items:
            type: string
          description: Returned on create and update when a step saves but should not ship as written — for example a `product` email whose body has no `{{unsubscribe_url}}` link.
    AutomationTrigger:
      type: object
      required:
      - type
      - event
      properties:
        type:
          type: string
          enum:
          - event
        event:
          type: string
          example: user.created
        cancel_on_events:
          type: array
          items:
            type: string
          maxItems: 20
          description: When any listed event fires for the same recipient, cancel queued/running/waiting runs for this automation.
        once_per_contact:
          type: boolean
          description: Enrol each recipient at most once, ever. Matched on the trigger event's `email` or `user_id`. A later matching event is reported in `enrollment_skips` instead of starting a run.
        cooldown_days:
          type: integer
          minimum: 1
          maximum: 3650
          description: Do not enrol the same recipient again within this many days of their last run on this automation. Ignored when `once_per_contact` is true.
    AutomationStep:
      type: object
      required:
      - type
      properties:
        type:
          type: string
          enum:
          - delay
          - send_email
          - send_sms
          - condition
          - wait_for_event
      additionalProperties: true
      description: 'Step object. Shape depends on `type`:

        - `delay`: `{ type, seconds }`

        - `send_email`: `{ type, email: { from, to, subject?, html?, text?, template?, category? } }`. `category` is `transactional` or `product` (`newsletter` is rejected); when omitted the step sends as its template''s category, else `transactional`. Merge fields accept a default: `{{event.data.name | default:"there"}}`. Values merged into `html` are HTML-escaped, and `{{unsubscribe_url}}` is filled in with the managed unsubscribe link.

        - `send_sms`: `{ type, sms: { to, body, from?, messaging_service_sid? } }` (requires Twilio integration)

        - `condition`: `{ type, path, operator, value? }` (false stops the run)

        - `wait_for_event`: `{ type, event, timeout_seconds?, on_timeout? }` (`on_timeout` is `continue` or `fail`, default `fail`)

        '
    EventRecord:
      type: object
      required:
      - id
      - name
      - user_id
      - email
      - data
      - source
      - created_at
      properties:
        id:
          type: string
        name:
          type: string
        user_id:
          type: string
          nullable: true
        email:
          type: string
          nullable: true
          format: email
        data:
          type: object
          additionalProperties: true
        source:
          type: string
          enum:
          - api
          - dashboard
        created_at:
          type: string
          format: date-time
    ErrorCode:
      type: string
      description: 'Stable, machine-readable error code. Each code is documented at

        `https://docs.groundmail.dev/errors#<code>`. New codes may be added;

        existing codes keep their meaning.


        - `validation_error` (400, 422): the request failed validation, or every recipient is suppressed or opted out (422). Fix the field named in `message`/`details`.

        - `unauthorized` (401): missing, malformed or revoked API key. Send `Authorization: Bearer gm_…`.

        - `forbidden` (403): the key is valid but the action is not allowed (unverified `from` domain, sandbox send to someone other than the account email, no payment method on file, sending restricted).

        - `insufficient_scope` (403): the API key''s scope does not cover this endpoint.

        - `domain_not_allowed` (403): the API key is limited to other sending domains than the one in `from`, or `from` is on another tenant''s domain.

        - `tenants_not_enabled` (403): the request names a tenant, but tenants are not enabled for this account. They are included on pay as you go and the Dedicated plan.

        - `newsletter_not_enabled` (403): the send uses `category: "newsletter"`, but newsletter sending isn''t enabled on this account. Newsletter email is accepted only for approved accounts.

        - `not_found` (404): no resource with that id for this team.

        - `conflict` (409): the resource already exists or its state blocks the change.

        - `plan_limit` (429): the plan''s monthly or daily sending limit was reached. See `upgrade_url`.

        - `daily_ramp_limit` (429): the send would go over a new account''s daily ramp-up limit for its stream, or its tenant''s own ramp or daily limit (`details.tenant`). Upgrading does not lift it; wait for `details.resets_at`.

        - `domain_limit` (403): the plan''s domain limit was reached. See `upgrade_url`.

        - `idempotency_conflict` (409): the `Idempotency-Key` was reused with a different body, or the first request is still running.

        - `rate_limited` (429): too many requests. Wait `Retry-After` seconds.

        - `timeout` (408): a long-poll (GET /test-inbox/wait) ended before a matching email arrived. Safe to call again.

        - `upstream_error` (502, 503, 504, or a passed-through 4xx): the mail server did not accept the request. 502/503 are safe to retry with the same `Idempotency-Key`; 504 means the outcome is unknown.

        - `not_configured` (503): the feature is temporarily unavailable.

        - `internal_error` (500): unexpected server error. Retry with backoff.

        '
      enum:
      - validation_error
      - unauthorized
      - forbidden
      - insufficient_scope
      - not_found
      - conflict
      - plan_limit
      - daily_ramp_limit
      - domain_limit
      - idempotency_conflict
      - rate_limited
      - timeout
      - upstream_error
      - not_configured
      - internal_error
      - domain_not_allowed
      - tenants_not_enabled
      - newsletter_not_enabled
    UpdateAutomationRequest:
      type: object
      properties:
        name:
          type: string
        trigger:
          $ref: '#/components/schemas/AutomationTrigger'
        steps:
          type: array
          items:
            $ref: '#/components/schemas/AutomationStep'
          minItems: 1
          maxItems: 20
        folder:
          type: string
          nullable: true
          maxLength: 64
          description: Move it to this folder, matched by name (any case) and created when it does not exist. `null` or an empty string takes it out of any folder.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'Groundmail API key (`gm_…`), OAuth access token (`gm_oat_…`), or a Microsoft Entra access token from an Azure managed identity registered in the dashboard (keyless; see https://docs.groundmail.dev/authentication/azure-managed-identity). All carry scopes; see the API description.

        '