---
title: "Update a welcome email"
method: PATCH
path: "/audiences/{id}/welcome-sequence/steps/{stepId}"
tags: ["Audiences"]
---

# Update a welcome email

`PATCH /audiences/{id}/welcome-sequence/steps/{stepId}`

## Request

- Base URL: `https://shipmail.to/api/v1`
- URL: `https://shipmail.to/api/v1/audiences/{id}/welcome-sequence/steps/{stepId}`
- 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`)

Change a welcome email's content, sender, tracking or wait. Readers already past it are not affected.

## Headers

- `Idempotency-Key` string
- `X-Shipmail-Organization` string

## Request body

- UpdateWelcomeStepRequest
  - `subject` string
  - `preview_text` string, nullable
  - `blocks` NewsletterBlock[]
    - union: Structured newsletter block. paragraph.body, quote.body, callout.body, list items, and column bodies accept bare text or restricted inline HTML. Shipmail sanitizes these values when it stores the blocks and renders email-safe HTML and text.
      - object
        - `type` 'heading', required
        - `text` string, required: Heading text.
        - `level` 1 | 2 | 3
      - object
        - `type` 'paragraph', required
        - `body` string, required: Bare text or sanitized inline HTML. Allowed tags: a, b, br, code, em, i, p, s, span, strong, and u. Use p or br for line breaks and HTML entities for literal tag-like text.
      - object
        - `type` 'list', required
        - `ordered` boolean
        - `items` string[], required
      - object
        - `type` 'callout', required
        - `title` string, nullable: Optional callout title.
        - `body` string, required: Bare text or sanitized inline HTML. Allowed tags: a, b, br, code, em, i, p, s, span, strong, and u. Use p or br for line breaks.
        - `variant` 'accent' | 'info' | 'warning' | 'success'
      - object
        - `type` 'button', required
        - `label` string, required: Button label.
        - `url` string, required: Absolute http, https, or mailto URL.
        - `align` 'left' | 'center' | 'right': Horizontal alignment of the button.
      - object
        - `type` 'image', required
        - `url` string, uri, required: Hosted HTTPS image URL.
        - `alt` string, required: Image alt text.
        - `align` 'left' | 'center' | 'right': Horizontal alignment of the image and its caption.
        - `link_url` string, nullable: Optional absolute http, https, or mailto image link.
        - `caption` string, nullable: Optional image caption.
        - `caption_url` string, nullable: Optional absolute http, https, or mailto caption link.
      - object
        - `type` 'video', required
        - `video_url` string, required: Absolute hosted video URL. Emails render this as a linked thumbnail.
        - `thumbnail_url` string, uri, required: Hosted HTTPS image thumbnail URL.
        - `label` string, required: Video link label.
      - object
        - `type` 'columns', required
        - `ratio` '50-50' | '33-67' | '67-33'
        - `left` union, required
          - object: Left column content. Include at least one heading, body, image, or CTA field.
            - `title` string, nullable, required: Optional column heading.
            - `body` string: Optional bare text or sanitized inline HTML. Allowed tags: a, b, br, code, em, i, p, s, span, strong, and u. Use p or br for line breaks.
            - `image_url` string, uri, nullable: Optional hosted HTTPS image URL.
            - `image_alt` string, nullable: Alt text for image_url.
            - `image_fit` 'natural' | 'contain' | 'cover': Optional image sizing. Natural preserves the source ratio; contain shows the whole image in a 4:3 frame; cover crops to fill a 4:3 frame.
            - `cta_label` string, nullable: Optional call-to-action label.
            - `cta_url` string, nullable: Optional http, https, or mailto call-to-action URL.
          - object: Left column content. Include at least one heading, body, image, or CTA field.
            - `body` string, required: Optional bare text or sanitized inline HTML. Allowed tags: a, b, br, code, em, i, p, s, span, strong, and u. Use p or br for line breaks.
            - `title` string, nullable: Optional column heading.
            - `image_url` string, uri, nullable: Optional hosted HTTPS image URL.
            - `image_alt` string, nullable: Alt text for image_url.
            - `image_fit` 'natural' | 'contain' | 'cover': Optional image sizing. Natural preserves the source ratio; contain shows the whole image in a 4:3 frame; cover crops to fill a 4:3 frame.
            - `cta_label` string, nullable: Optional call-to-action label.
            - `cta_url` string, nullable: Optional http, https, or mailto call-to-action URL.
          - object: Left column content. Include at least one heading, body, image, or CTA field.
            - `image_url` string, uri, nullable, required: Optional hosted HTTPS image URL.
            - `title` string, nullable: Optional column heading.
            - `body` string: Optional bare text or sanitized inline HTML. Allowed tags: a, b, br, code, em, i, p, s, span, strong, and u. Use p or br for line breaks.
            - `image_alt` string, nullable: Alt text for image_url.
            - `image_fit` 'natural' | 'contain' | 'cover': Optional image sizing. Natural preserves the source ratio; contain shows the whole image in a 4:3 frame; cover crops to fill a 4:3 frame.
            - `cta_label` string, nullable: Optional call-to-action label.
            - `cta_url` string, nullable: Optional http, https, or mailto call-to-action URL.
          - object: Left column content. Include at least one heading, body, image, or CTA field.
            - `cta_label` string, nullable, required: Optional call-to-action label.
            - `cta_url` string, nullable, required: Optional http, https, or mailto call-to-action URL.
            - `title` string, nullable: Optional column heading.
            - `body` string: Optional bare text or sanitized inline HTML. Allowed tags: a, b, br, code, em, i, p, s, span, strong, and u. Use p or br for line breaks.
            - `image_url` string, uri, nullable: Optional hosted HTTPS image URL.
            - `image_alt` string, nullable: Alt text for image_url.
            - `image_fit` 'natural' | 'contain' | 'cover': Optional image sizing. Natural preserves the source ratio; contain shows the whole image in a 4:3 frame; cover crops to fill a 4:3 frame.
        - `right` union, required
          - object: Right column content. Include at least one heading, body, image, or CTA field.
            - `title` string, nullable, required: Optional column heading.
            - `body` string: Optional bare text or sanitized inline HTML. Allowed tags: a, b, br, code, em, i, p, s, span, strong, and u. Use p or br for line breaks.
            - `image_url` string, uri, nullable: Optional hosted HTTPS image URL.
            - `image_alt` string, nullable: Alt text for image_url.
            - `image_fit` 'natural' | 'contain' | 'cover': Optional image sizing. Natural preserves the source ratio; contain shows the whole image in a 4:3 frame; cover crops to fill a 4:3 frame.
            - `cta_label` string, nullable: Optional call-to-action label.
            - `cta_url` string, nullable: Optional http, https, or mailto call-to-action URL.
          - object: Right column content. Include at least one heading, body, image, or CTA field.
            - `body` string, required: Optional bare text or sanitized inline HTML. Allowed tags: a, b, br, code, em, i, p, s, span, strong, and u. Use p or br for line breaks.
            - `title` string, nullable: Optional column heading.
            - `image_url` string, uri, nullable: Optional hosted HTTPS image URL.
            - `image_alt` string, nullable: Alt text for image_url.
            - `image_fit` 'natural' | 'contain' | 'cover': Optional image sizing. Natural preserves the source ratio; contain shows the whole image in a 4:3 frame; cover crops to fill a 4:3 frame.
            - `cta_label` string, nullable: Optional call-to-action label.
            - `cta_url` string, nullable: Optional http, https, or mailto call-to-action URL.
          - object: Right column content. Include at least one heading, body, image, or CTA field.
            - `image_url` string, uri, nullable, required: Optional hosted HTTPS image URL.
            - `title` string, nullable: Optional column heading.
            - `body` string: Optional bare text or sanitized inline HTML. Allowed tags: a, b, br, code, em, i, p, s, span, strong, and u. Use p or br for line breaks.
            - `image_alt` string, nullable: Alt text for image_url.
            - `image_fit` 'natural' | 'contain' | 'cover': Optional image sizing. Natural preserves the source ratio; contain shows the whole image in a 4:3 frame; cover crops to fill a 4:3 frame.
            - `cta_label` string, nullable: Optional call-to-action label.
            - `cta_url` string, nullable: Optional http, https, or mailto call-to-action URL.
          - object: Right column content. Include at least one heading, body, image, or CTA field.
            - `cta_label` string, nullable, required: Optional call-to-action label.
            - `cta_url` string, nullable, required: Optional http, https, or mailto call-to-action URL.
            - `title` string, nullable: Optional column heading.
            - `body` string: Optional bare text or sanitized inline HTML. Allowed tags: a, b, br, code, em, i, p, s, span, strong, and u. Use p or br for line breaks.
            - `image_url` string, uri, nullable: Optional hosted HTTPS image URL.
            - `image_alt` string, nullable: Alt text for image_url.
            - `image_fit` 'natural' | 'contain' | 'cover': Optional image sizing. Natural preserves the source ratio; contain shows the whole image in a 4:3 frame; cover crops to fill a 4:3 frame.
      - object
        - `type` 'link_list', required
        - `title` string, nullable: Optional link list title.
        - `items` object[], required
          - `label` string, required: Link label.
          - `url` string, required: Absolute http, https, or mailto URL.
          - `description` string, nullable: Optional description shown under the link.
      - object
        - `type` 'quote', required
        - `body` string, required: Bare text or sanitized inline HTML. Allowed tags: a, b, br, code, em, i, p, s, span, strong, and u. Use p or br for line breaks.
        - `cite` string, nullable: Optional quote citation.
      - object
        - `type` 'divider', required
      - object
        - `type` 'spacer', required
        - `height` integer
      - object
        - `type` 'code', required
        - `code` string, required: Code text.
      - object
        - `type` 'custom_html', required
        - `html` string, required: Custom email-safe HTML fragment.
  - `content_markdown` string: The body as Markdown, converted to blocks on the server. Send blocks or content_markdown, not both.
  - `wait_minutes` integer
  - `sender_identity_id` string: Defaults to the organization's default sender identity.
  - `track_engagement` boolean
  - `add_utm_tags` boolean
  - `styling_mode` 'styled' | 'plain'

## Response `200`

The updated welcome email.

- WelcomeStep
  - `object` 'welcome_step', required
  - `id` string, required
  - `audience_id` string, nullable, required
  - `position` integer, required: Order in the sequence. Positions only grow; gaps are normal.
  - `wait_minutes` integer, required: Minutes after the previous email (or after the subscribe, for the first email) before this one is sent.
  - `sender_identity_id` string, nullable, required
  - `subject` string, nullable, required
  - `preview_text` string, nullable, required
  - `blocks` NewsletterBlock[], required
    - union: Structured newsletter block. paragraph.body, quote.body, callout.body, list items, and column bodies accept bare text or restricted inline HTML. Shipmail sanitizes these values when it stores the blocks and renders email-safe HTML and text.
      - object
        - `type` 'heading', required
        - `text` string, required: Heading text.
        - `level` 1 | 2 | 3
      - object
        - `type` 'paragraph', required
        - `body` string, required: Bare text or sanitized inline HTML. Allowed tags: a, b, br, code, em, i, p, s, span, strong, and u. Use p or br for line breaks and HTML entities for literal tag-like text.
      - object
        - `type` 'list', required
        - `ordered` boolean
        - `items` string[], required
      - object
        - `type` 'callout', required
        - `title` string, nullable: Optional callout title.
        - `body` string, required: Bare text or sanitized inline HTML. Allowed tags: a, b, br, code, em, i, p, s, span, strong, and u. Use p or br for line breaks.
        - `variant` 'accent' | 'info' | 'warning' | 'success'
      - object
        - `type` 'button', required
        - `label` string, required: Button label.
        - `url` string, required: Absolute http, https, or mailto URL.
        - `align` 'left' | 'center' | 'right': Horizontal alignment of the button.
      - object
        - `type` 'image', required
        - `url` string, uri, required: Hosted HTTPS image URL.
        - `alt` string, required: Image alt text.
        - `align` 'left' | 'center' | 'right': Horizontal alignment of the image and its caption.
        - `link_url` string, nullable: Optional absolute http, https, or mailto image link.
        - `caption` string, nullable: Optional image caption.
        - `caption_url` string, nullable: Optional absolute http, https, or mailto caption link.
      - object
        - `type` 'video', required
        - `video_url` string, required: Absolute hosted video URL. Emails render this as a linked thumbnail.
        - `thumbnail_url` string, uri, required: Hosted HTTPS image thumbnail URL.
        - `label` string, required: Video link label.
      - object
        - `type` 'columns', required
        - `ratio` '50-50' | '33-67' | '67-33'
        - `left` union, required
          - object: Left column content. Include at least one heading, body, image, or CTA field.
            - `title` string, nullable, required: Optional column heading.
            - `body` string: Optional bare text or sanitized inline HTML. Allowed tags: a, b, br, code, em, i, p, s, span, strong, and u. Use p or br for line breaks.
            - `image_url` string, uri, nullable: Optional hosted HTTPS image URL.
            - `image_alt` string, nullable: Alt text for image_url.
            - `image_fit` 'natural' | 'contain' | 'cover': Optional image sizing. Natural preserves the source ratio; contain shows the whole image in a 4:3 frame; cover crops to fill a 4:3 frame.
            - `cta_label` string, nullable: Optional call-to-action label.
            - `cta_url` string, nullable: Optional http, https, or mailto call-to-action URL.
          - object: Left column content. Include at least one heading, body, image, or CTA field.
            - `body` string, required: Optional bare text or sanitized inline HTML. Allowed tags: a, b, br, code, em, i, p, s, span, strong, and u. Use p or br for line breaks.
            - `title` string, nullable: Optional column heading.
            - `image_url` string, uri, nullable: Optional hosted HTTPS image URL.
            - `image_alt` string, nullable: Alt text for image_url.
            - `image_fit` 'natural' | 'contain' | 'cover': Optional image sizing. Natural preserves the source ratio; contain shows the whole image in a 4:3 frame; cover crops to fill a 4:3 frame.
            - `cta_label` string, nullable: Optional call-to-action label.
            - `cta_url` string, nullable: Optional http, https, or mailto call-to-action URL.
          - object: Left column content. Include at least one heading, body, image, or CTA field.
            - `image_url` string, uri, nullable, required: Optional hosted HTTPS image URL.
            - `title` string, nullable: Optional column heading.
            - `body` string: Optional bare text or sanitized inline HTML. Allowed tags: a, b, br, code, em, i, p, s, span, strong, and u. Use p or br for line breaks.
            - `image_alt` string, nullable: Alt text for image_url.
            - `image_fit` 'natural' | 'contain' | 'cover': Optional image sizing. Natural preserves the source ratio; contain shows the whole image in a 4:3 frame; cover crops to fill a 4:3 frame.
            - `cta_label` string, nullable: Optional call-to-action label.
            - `cta_url` string, nullable: Optional http, https, or mailto call-to-action URL.
          - object: Left column content. Include at least one heading, body, image, or CTA field.
            - `cta_label` string, nullable, required: Optional call-to-action label.
            - `cta_url` string, nullable, required: Optional http, https, or mailto call-to-action URL.
            - `title` string, nullable: Optional column heading.
            - `body` string: Optional bare text or sanitized inline HTML. Allowed tags: a, b, br, code, em, i, p, s, span, strong, and u. Use p or br for line breaks.
            - `image_url` string, uri, nullable: Optional hosted HTTPS image URL.
            - `image_alt` string, nullable: Alt text for image_url.
            - `image_fit` 'natural' | 'contain' | 'cover': Optional image sizing. Natural preserves the source ratio; contain shows the whole image in a 4:3 frame; cover crops to fill a 4:3 frame.
        - `right` union, required
          - object: Right column content. Include at least one heading, body, image, or CTA field.
            - `title` string, nullable, required: Optional column heading.
            - `body` string: Optional bare text or sanitized inline HTML. Allowed tags: a, b, br, code, em, i, p, s, span, strong, and u. Use p or br for line breaks.
            - `image_url` string, uri, nullable: Optional hosted HTTPS image URL.
            - `image_alt` string, nullable: Alt text for image_url.
            - `image_fit` 'natural' | 'contain' | 'cover': Optional image sizing. Natural preserves the source ratio; contain shows the whole image in a 4:3 frame; cover crops to fill a 4:3 frame.
            - `cta_label` string, nullable: Optional call-to-action label.
            - `cta_url` string, nullable: Optional http, https, or mailto call-to-action URL.
          - object: Right column content. Include at least one heading, body, image, or CTA field.
            - `body` string, required: Optional bare text or sanitized inline HTML. Allowed tags: a, b, br, code, em, i, p, s, span, strong, and u. Use p or br for line breaks.
            - `title` string, nullable: Optional column heading.
            - `image_url` string, uri, nullable: Optional hosted HTTPS image URL.
            - `image_alt` string, nullable: Alt text for image_url.
            - `image_fit` 'natural' | 'contain' | 'cover': Optional image sizing. Natural preserves the source ratio; contain shows the whole image in a 4:3 frame; cover crops to fill a 4:3 frame.
            - `cta_label` string, nullable: Optional call-to-action label.
            - `cta_url` string, nullable: Optional http, https, or mailto call-to-action URL.
          - object: Right column content. Include at least one heading, body, image, or CTA field.
            - `image_url` string, uri, nullable, required: Optional hosted HTTPS image URL.
            - `title` string, nullable: Optional column heading.
            - `body` string: Optional bare text or sanitized inline HTML. Allowed tags: a, b, br, code, em, i, p, s, span, strong, and u. Use p or br for line breaks.
            - `image_alt` string, nullable: Alt text for image_url.
            - `image_fit` 'natural' | 'contain' | 'cover': Optional image sizing. Natural preserves the source ratio; contain shows the whole image in a 4:3 frame; cover crops to fill a 4:3 frame.
            - `cta_label` string, nullable: Optional call-to-action label.
            - `cta_url` string, nullable: Optional http, https, or mailto call-to-action URL.
          - object: Right column content. Include at least one heading, body, image, or CTA field.
            - `cta_label` string, nullable, required: Optional call-to-action label.
            - `cta_url` string, nullable, required: Optional http, https, or mailto call-to-action URL.
            - `title` string, nullable: Optional column heading.
            - `body` string: Optional bare text or sanitized inline HTML. Allowed tags: a, b, br, code, em, i, p, s, span, strong, and u. Use p or br for line breaks.
            - `image_url` string, uri, nullable: Optional hosted HTTPS image URL.
            - `image_alt` string, nullable: Alt text for image_url.
            - `image_fit` 'natural' | 'contain' | 'cover': Optional image sizing. Natural preserves the source ratio; contain shows the whole image in a 4:3 frame; cover crops to fill a 4:3 frame.
      - object
        - `type` 'link_list', required
        - `title` string, nullable: Optional link list title.
        - `items` object[], required
          - `label` string, required: Link label.
          - `url` string, required: Absolute http, https, or mailto URL.
          - `description` string, nullable: Optional description shown under the link.
      - object
        - `type` 'quote', required
        - `body` string, required: Bare text or sanitized inline HTML. Allowed tags: a, b, br, code, em, i, p, s, span, strong, and u. Use p or br for line breaks.
        - `cite` string, nullable: Optional quote citation.
      - object
        - `type` 'divider', required
      - object
        - `type` 'spacer', required
        - `height` integer
      - object
        - `type` 'code', required
        - `code` string, required: Code text.
      - object
        - `type` 'custom_html', required
        - `html` string, required: Custom email-safe HTML fragment.
  - `track_engagement` boolean, required
  - `add_utm_tags` boolean, required
  - `styling_mode` 'styled' | 'plain', required
  - `sent_count` integer, required
  - `delivered_count` integer, required
  - `bounced_count` integer, required
  - `complained_count` integer, required
  - `created_at` string, date-time, required
  - `updated_at` string, date-time, required

## Other responses

- `404`: Resource not found.
- `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)