---
title: "Update an automation"
method: PUT
path: "/v1/automations/{automation_id}"
tags: ["Automations"]
---

# Update an automation

`PUT /v1/automations/{automation_id}`

## Request

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

Updates an existing draft or paused Automation. Before changing a running Automation, read it by ID, retain its status in the current task only, pause it, apply the update, and use bounded direct item reads until is_updating is false. Run preflight, return it to running only if it was running before and preflight passes, and verify the final status. If the update fails before changing the Automation, restore its prior running status when preflight passes. If readiness or the prior status cannot be restored, leave it paused and immediately report the failure; never activate an Automation that was not already running.

## Path parameters

- `automation_id` string, required

## Request body

- AutomationUpdateRequest
  - `name` string
  - `definition` AutomationDefinition
    - `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 `200`

Successful response

- 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
- `404`: Resource not found
- `409`: A running Automation must be paused before it can be updated. Before changing a running Automation, read it by ID, retain its status in the current task only, pause it, apply the update, and use bounded direct item reads until is_updating is false. Run preflight, return it to running only if it was running before and preflight passes, and verify the final status. If the update fails before changing the Automation, restore its prior running status when preflight passes. If readiness or the prior status cannot be restored, leave it paused and immediately report the failure; never activate an Automation that was not already running.

---

[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)