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

# Create an automation

`POST /v1/automations`

## Request

- Base URL: `https://api.mailrith.com`
- URL: `https://api.mailrith.com/v1/automations`
- Auth: HTTP bearer

Creates an automation in the authenticated workspace.

## Headers

- `Idempotency-Key` string

## Request body

- AutomationUpsertRequest
  - `name` string, required
  - `definition` AutomationDefinition, required
    - `version` 2
    - `trigger` AutomationTrigger
      - `type` 'tag_added' | 'tag_removed' | 'magic_link_clicked' | 'subscriber_status', required
      - `tagId` string, nullable
      - `tagIds` string[]
      - `magicLinkId` string, nullable
      - `magicLinkIds` string[]
      - `operator` 'is' | 'is_not'
      - `statuses` string[]
    - `triggers` AutomationTrigger[]
      - `type` 'tag_added' | 'tag_removed' | 'magic_link_clicked' | 'subscriber_status', required
      - `tagId` string, nullable
      - `tagIds` string[]
      - `magicLinkId` string, nullable
      - `magicLinkIds` string[]
      - `operator` 'is' | 'is_not'
      - `statuses` string[]
    - `entryPoints` AutomationEntryPoint[]
      - `id` string, required
      - `trigger` AutomationTrigger, required
        - `type` 'tag_added' | 'tag_removed' | 'magic_link_clicked' | 'subscriber_status', required
        - `tagId` string, nullable
        - `tagIds` string[]
        - `magicLinkId` string, nullable
        - `magicLinkIds` string[]
        - `operator` 'is' | 'is_not'
        - `statuses` string[]
      - `name` string, nullable
      - `description` string, nullable
    - `steps` AutomationStep[], required
      - `id` string, required
      - `kind` 'event' | 'action' | 'condition', required
      - `type` 'tag_added' | 'tag_removed' | 'magic_link_clicked' | 'sequence_completed' | 'add_tag' | 'remove_tag' | 'add_to_sequence' | 'remove_from_sequence' | 'change_subscriber_status' | 'wait' | 'update_custom_field' | 'send_email' | 'send_internal_notification' | 'start_automation' | 'remove_from_automation' | 'webhook' | 'end_automation' | 'has_tag' | 'custom_field_match' | 'sequence_membership' | 'subscriber_status' | 'email_opened' | 'email_clicked', required
      - `config` AutomationStepConfig
        - `tagId` string
        - `sequenceId` string
        - `magicLinkId` string
        - `customFieldId` string
        - `automationId` string
        - `emailId` string
        - `status` string
        - `statuses` string[]
        - `operation` 'set' | 'clear' | 'increment' | 'decrement' | 'set_today' | 'add_choices' | 'remove_choices' | 'set_true' | 'set_false' | 'toggle'
        - `operator` 'equals' | 'not_equals' | 'contains' | 'not_contains' | 'starts_with' | 'ends_with' | 'exists' | 'missing' | 'greater_than' | 'greater_than_or_equal' | 'less_than' | 'less_than_or_equal' | 'on' | 'not_on' | 'before' | 'on_or_before' | 'after' | 'on_or_after' | 'contains_any' | 'contains_all' | 'does_not_contain_any' | 'is_checked' | 'is_not_checked'
        - `value` union
          - string
          - number
          - boolean
          - string[]
        - `mode` 'duration' | 'until_custom_date' | 'until_custom_field_date'
        - `waitMode` 'duration' | 'custom_date'
        - `dateSource` 'custom_field' | 'fixed_date'
        - `date` string, date
        - `timeOfDay` string
        - `durationValue` number
        - `durationUnit` 'minute' | 'hour' | 'day' | 'week'
        - `waitForCompletion` boolean
        - `waitUntilComplete` boolean
        - `exitNextStepId` string, nullable
        - `lookbackDays` integer
        - `recipientEmail` string, email
        - `subject` string: For Subscriber personalization in email subjects and body text nodes, use Mailrith bracket tokens such as [Subscriber_Name, fallback="friend"] or [Subscriber_Email, fallback=""]. Before using a custom field, call custom_fields_list or custom_fields_get and copy its personalization_token exactly. Do not use Handlebars-style variables such as {{ subscriber.name }}; Mailrith sends them as literal text.
        - `previewText` string
        - `bodyDocument` BroadcastEmailDocument
          - `type` 'doc' | 'paragraph' | 'heading' | 'text' | 'hardBreak' | 'bulletList' | 'orderedList' | 'listItem' | 'blockquote' | 'emailSection' | 'emailSectionColumn' | 'emailButton' | 'image' | 'horizontalRule', required
          - `attrs` object
            - `id` string
            - `level` 1 | 2 | 3
            - `textAlign` 'left' | 'center' | 'right' | 'justify'
            - `columns` 1 | 2 | 3
            - `width` 'default' | 'large' | 'full' | 'fit'
            - `backgroundColor` string
            - `blockquoteBorderColor` string
            - `linkColor` string
            - `layoutAlignment` 'left' | 'center'
            - `backgroundImageUrl` string
            - `margin` 'none' | 'normal' | 'large'
            - `padding` 'none' | 'normal' | 'large'
            - `borderColor` string
            - `borderWidth` 'none' | 'normal' | 'large'
            - `borderRadius` 'none' | 'normal' | 'small' | 'large' | 'full'
            - `verticalAlign` 'top' | 'middle' | 'bottom'
            - `href` string
            - `textColor` string
            - `size` 'small' | 'medium' | 'large'
            - `align` 'left' | 'center' | 'right'
            - `label` string
            - `src` string
            - `alt` string
            - `title` string
            - `caption` string
            - `source` 'unsplash'
            - `unsplash` object
              - …
            - `widthPercent` number
            - `crop` 'none' | 'square' | 'circle'
            - `fillColumn` boolean
          - `content` BroadcastEmailNode[]
            - `type` 'doc' | 'paragraph' | 'heading' | 'text' | 'hardBreak' | 'bulletList' | 'orderedList' | 'listItem' | 'blockquote' | 'emailSection' | 'emailSectionColumn' | 'emailButton' | 'image' | 'horizontalRule', required
            - `attrs` object
              - …
            - `content` BroadcastEmailNode[]
            - `text` string
            - `marks` BroadcastEmailMark[]
              - …
          - `text` string
          - `marks` BroadcastEmailMark[]
            - `type` 'bold' | 'italic' | 'strike' | 'underline' | 'link' | 'textStyle' | 'highlight', required
            - `attrs` object
              - …
        - `replyToEmail` string
        - `trackOpens` boolean
        - `trackClicks` boolean
        - `utmSource` string
        - `utmMedium` string
        - `utmCampaign` string
        - `utmTerm` string
        - `utmContent` string
        - `url` string, uri
        - `method` 'POST' | 'PUT' | 'PATCH'
        - `authType` 'none' | 'bearer'
        - `bearerToken` string
        - `bearerTokenConfigured` boolean: True when Mailrith has a saved webhook bearer token. Send this unchanged during an update to preserve the saved value. The token value is never returned.
        - `headers` object[]
          - `key` string, required
          - `value` string: A secret header value accepted on writes and never returned.
          - `configured` boolean: True when Mailrith has a saved value for this header. Send this unchanged during an update to preserve the saved value.
        - `includeSubscriber` boolean
        - `includeTags` boolean
        - `includeCustomFields` boolean
      - `stats` EmailEngagementStats
        - `recipientCount` integer, required
        - `engagedCount` integer
        - `openedCount` integer, required
        - `clickedCount` integer, required
        - `clickedSubscriberCount` integer
        - `unsubscribedCount` integer, required
        - `bouncedCount` integer
        - `complainedCount` integer
        - `sentCountsByDay` object
      - `note` string, nullable
      - `nextStepId` string, nullable
      - `branches` object
      - `paths` AutomationPath[]
        - `id` string, required
        - `label` string, required
        - `nextStepId` string, nullable
        - `weight` number, nullable

## Response `201`

Automation created

- object
  - `data` Automation, required
    - `self` string, required: Stable relative Public API path for retrieving this resource.
    - `id` string, required
    - `name` string, required
    - `status` 'draft' | 'running' | 'paused', required
    - `is_updating` boolean, required: True while Mailrith updates existing Subscriber progress after a structural Automation change.
    - `definition` AutomationDefinition, required
      - `version` 2
      - `trigger` AutomationTrigger
        - `type` 'tag_added' | 'tag_removed' | 'magic_link_clicked' | 'subscriber_status', required
        - `tagId` string, nullable
        - `tagIds` string[]
        - `magicLinkId` string, nullable
        - `magicLinkIds` string[]
        - `operator` 'is' | 'is_not'
        - `statuses` string[]
      - `triggers` AutomationTrigger[]
        - `type` 'tag_added' | 'tag_removed' | 'magic_link_clicked' | 'subscriber_status', required
        - `tagId` string, nullable
        - `tagIds` string[]
        - `magicLinkId` string, nullable
        - `magicLinkIds` string[]
        - `operator` 'is' | 'is_not'
        - `statuses` string[]
      - `entryPoints` AutomationEntryPoint[]
        - `id` string, required
        - `trigger` AutomationTrigger, required
          - `type` 'tag_added' | 'tag_removed' | 'magic_link_clicked' | 'subscriber_status', required
          - `tagId` string, nullable
          - `tagIds` string[]
          - `magicLinkId` string, nullable
          - `magicLinkIds` string[]
          - `operator` 'is' | 'is_not'
          - `statuses` string[]
        - `name` string, nullable
        - `description` string, nullable
      - `steps` AutomationStep[], required
        - `id` string, required
        - `kind` 'event' | 'action' | 'condition', required
        - `type` 'tag_added' | 'tag_removed' | 'magic_link_clicked' | 'sequence_completed' | 'add_tag' | 'remove_tag' | 'add_to_sequence' | 'remove_from_sequence' | 'change_subscriber_status' | 'wait' | 'update_custom_field' | 'send_email' | 'send_internal_notification' | 'start_automation' | 'remove_from_automation' | 'webhook' | 'end_automation' | 'has_tag' | 'custom_field_match' | 'sequence_membership' | 'subscriber_status' | 'email_opened' | 'email_clicked', required
        - `config` AutomationStepConfig
          - `tagId` string
          - `sequenceId` string
          - `magicLinkId` string
          - `customFieldId` string
          - `automationId` string
          - `emailId` string
          - `status` string
          - `statuses` string[]
          - `operation` 'set' | 'clear' | 'increment' | 'decrement' | 'set_today' | 'add_choices' | 'remove_choices' | 'set_true' | 'set_false' | 'toggle'
          - `operator` 'equals' | 'not_equals' | 'contains' | 'not_contains' | 'starts_with' | 'ends_with' | 'exists' | 'missing' | 'greater_than' | 'greater_than_or_equal' | 'less_than' | 'less_than_or_equal' | 'on' | 'not_on' | 'before' | 'on_or_before' | 'after' | 'on_or_after' | 'contains_any' | 'contains_all' | 'does_not_contain_any' | 'is_checked' | 'is_not_checked'
          - `value` union
            - string
            - number
            - boolean
            - string[]
          - `mode` 'duration' | 'until_custom_date' | 'until_custom_field_date'
          - `waitMode` 'duration' | 'custom_date'
          - `dateSource` 'custom_field' | 'fixed_date'
          - `date` string, date
          - `timeOfDay` string
          - `durationValue` number
          - `durationUnit` 'minute' | 'hour' | 'day' | 'week'
          - `waitForCompletion` boolean
          - `waitUntilComplete` boolean
          - `exitNextStepId` string, nullable
          - `lookbackDays` integer
          - `recipientEmail` string, email
          - `subject` string: For Subscriber personalization in email subjects and body text nodes, use Mailrith bracket tokens such as [Subscriber_Name, fallback="friend"] or [Subscriber_Email, fallback=""]. Before using a custom field, call custom_fields_list or custom_fields_get and copy its personalization_token exactly. Do not use Handlebars-style variables such as {{ subscriber.name }}; Mailrith sends them as literal text.
          - `previewText` string
          - `bodyDocument` BroadcastEmailDocument
            - `type` 'doc' | 'paragraph' | 'heading' | 'text' | 'hardBreak' | 'bulletList' | 'orderedList' | 'listItem' | 'blockquote' | 'emailSection' | 'emailSectionColumn' | 'emailButton' | 'image' | 'horizontalRule', required
            - `attrs` object
              - …
            - `content` BroadcastEmailNode[]
              - …
            - `text` string
            - `marks` BroadcastEmailMark[]
              - …
          - `replyToEmail` string
          - `trackOpens` boolean
          - `trackClicks` boolean
          - `utmSource` string
          - `utmMedium` string
          - `utmCampaign` string
          - `utmTerm` string
          - `utmContent` string
          - `url` string, uri
          - `method` 'POST' | 'PUT' | 'PATCH'
          - `authType` 'none' | 'bearer'
          - `bearerToken` string
          - `bearerTokenConfigured` boolean: True when Mailrith has a saved webhook bearer token. Send this unchanged during an update to preserve the saved value. The token value is never returned.
          - `headers` object[]
            - `key` string, required
            - `value` string: A secret header value accepted on writes and never returned.
            - `configured` boolean: True when Mailrith has a saved value for this header. Send this unchanged during an update to preserve the saved value.
          - `includeSubscriber` boolean
          - `includeTags` boolean
          - `includeCustomFields` boolean
        - `stats` EmailEngagementStats
          - `recipientCount` integer, required
          - `engagedCount` integer
          - `openedCount` integer, required
          - `clickedCount` integer, required
          - `clickedSubscriberCount` integer
          - `unsubscribedCount` integer, required
          - `bouncedCount` integer
          - `complainedCount` integer
          - `sentCountsByDay` object
        - `note` string, nullable
        - `nextStepId` string, nullable
        - `branches` object
        - `paths` AutomationPath[]
          - `id` string, required
          - `label` string, required
          - `nextStepId` string, nullable
          - `weight` number, nullable
    - `subscriber_count` integer, required
    - `created_at` string, date-time, required
    - `updated_at` string, date-time, required

## Other responses

- `400`: Request is invalid

---

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