---
title: "Create an automation"
method: POST
path: "/automations"
tags: ["Automations"]
---

# Create an automation

`POST /automations`

## Request

- Base URL: `https://shipmail.to/api/v1`
- URL: `https://shipmail.to/api/v1/automations`
- Auth: one of:
  - HTTP bearer
  - OAuth 2 (authorization code, authorization URL `https://shipmail.to/api/auth/oauth2/authorize`, token URL `https://shipmail.to/api/auth/oauth2/token`)

Create and atomically activate an automation from an explicit reviewed definition.

## Headers

- `X-Shipmail-Organization` string

## Request body

- CreateAutomationRequest
  - `name` string, required
  - `definition` AutomationDefinition, required
    - `trigger` union, required
      - object
        - `type` 'email_received', required
        - `mailbox_ids` string[], required
      - object
        - `type` 'scheduled', required
        - `cron` string, required: Five-field daily or weekly cron expression.
        - `time_zone` string, required: IANA time zone.
      - object
        - `type` 'manual', required
        - `mailbox_ids` string[], required
      - object
        - `type` 'thread_state', required
        - `mailbox_ids` string[], required
        - `state` 'no_reply_after', required
        - `duration_minutes` integer, required
    - `conditions` AutomationCondition[], required
      - union
        - object
          - `type` 'sender_address', required
          - `addresses` string[], required
        - object
          - `type` 'sender_domain', required
          - `domains` string[], required
        - object
          - `type` 'subject_contains', required
          - `values` string[], required
        - object
          - `type` 'has_attachment', required
          - `value` boolean, required
        - object
          - `type` 'semantic_positive_match', required
          - `instruction` string, required
          - `minimum_confidence` number, required
    - `actions` AutomationAction[], required
      - union
        - object
          - `type` 'create_reply_draft', required
          - `instruction` string, required
        - object
          - `type` 'reply_to_trigger_sender', required
          - `instruction` string, required
        - object
          - `type` 'archive_trigger_message', required
        - object
          - `type` 'move_trigger_message', required
          - `mailbox_id` string, required
          - `destination_folder_id` string, required
        - object
          - `type` 'set_trigger_read_state', required
          - `is_read` boolean, required
        - object
          - `type` 'set_trigger_star_state', required
          - `is_starred` boolean, required
        - object
          - `type` 'generate_mail_report', required
          - `metric` 'received' | 'sent' | 'unread', required
          - `lookback_minutes` integer, required
    - `mode` 'draft' | 'send', required: Send mode is allowed only for one deterministic reply action on email_received.
    - `scope` object, required
      - `mailbox_ids` string[], required
      - `calendar_addresses` string[], required

## Response `201`

Automation created and activated.

- Automation
  - `object` 'automation', required
  - `id` string, required
  - `name` string, required
  - `status` 'active' | 'paused' | 'disabled', required
  - `version_id` string, required
  - `version` integer, required
  - `definition` AutomationDefinition, required
    - `trigger` union, required
      - object
        - `type` 'email_received', required
        - `mailbox_ids` string[], required
      - object
        - `type` 'scheduled', required
        - `cron` string, required: Five-field daily or weekly cron expression.
        - `time_zone` string, required: IANA time zone.
      - object
        - `type` 'manual', required
        - `mailbox_ids` string[], required
      - object
        - `type` 'thread_state', required
        - `mailbox_ids` string[], required
        - `state` 'no_reply_after', required
        - `duration_minutes` integer, required
    - `conditions` AutomationCondition[], required
      - union
        - object
          - `type` 'sender_address', required
          - `addresses` string[], required
        - object
          - `type` 'sender_domain', required
          - `domains` string[], required
        - object
          - `type` 'subject_contains', required
          - `values` string[], required
        - object
          - `type` 'has_attachment', required
          - `value` boolean, required
        - object
          - `type` 'semantic_positive_match', required
          - `instruction` string, required
          - `minimum_confidence` number, required
    - `actions` AutomationAction[], required
      - union
        - object
          - `type` 'create_reply_draft', required
          - `instruction` string, required
        - object
          - `type` 'reply_to_trigger_sender', required
          - `instruction` string, required
        - object
          - `type` 'archive_trigger_message', required
        - object
          - `type` 'move_trigger_message', required
          - `mailbox_id` string, required
          - `destination_folder_id` string, required
        - object
          - `type` 'set_trigger_read_state', required
          - `is_read` boolean, required
        - object
          - `type` 'set_trigger_star_state', required
          - `is_starred` boolean, required
        - object
          - `type` 'generate_mail_report', required
          - `metric` 'received' | 'sent' | 'unread', required
          - `lookback_minutes` integer, required
    - `mode` 'draft' | 'send', required: Send mode is allowed only for one deterministic reply action on email_received.
    - `scope` object, required
      - `mailbox_ids` string[], required
      - `calendar_addresses` string[], required
  - `last_run` AutomationRunSummary, required
    - `object` 'automation_run', required
    - `id` string, required
    - `status` 'queued' | 'running' | 'completed' | 'failed' | 'degraded' | 'cancelled' | 'skipped', required
    - `error_code` string, nullable, required
    - `created_at` string, date-time, required
  - `next_run_at` string, date-time, nullable, required
  - `created_at` string, date-time, required
  - `updated_at` string, date-time, required

## Other responses

- `403`: Insufficient permissions.
- `422`: Validation failed.
- `429`: Rate limit exceeded.

---

[API](https://skmtc.dev/shipmail/apis/shipmail-api.md) · [All operations](https://skmtc.dev/shipmail/apis/shipmail-api/llms.txt) · [OpenAPI document](https://skmtc.dev/shipmail/apis/shipmail-api/revisions/2c23e59d7e30?raw)