--- title: "Turn the welcome sequence on or off" method: PATCH path: "/audiences/{id}/welcome-sequence" tags: ["Audiences"] --- # Turn the welcome sequence on or off `PATCH /audiences/{id}/welcome-sequence` ## Request - Base URL: `https://shipmail.to/api/v1` - URL: `https://shipmail.to/api/v1/audiences/{id}/welcome-sequence` - 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`) Turn the sequence on or off. While it is on, readers who subscribe through a signup form or the API (or confirm, with double opt-in) get its emails through the newsletter send path: the same footer, unsubscribe headers, suppressions and monthly limit as newsletters. At most 100 welcome emails per audience go out in any ten minutes; the rest wait, and the owner gets an email. ## Headers - `Idempotency-Key` string - `X-Shipmail-Organization` string ## Request body - UpdateWelcomeSequenceRequest - `enabled` boolean, required: Turn the sequence on or off. Turning it on needs at least one email with a subject and a body, and resumes a paused sequence. ## Response `200` The updated welcome sequence. - WelcomeSequence - `object` 'welcome_sequence', required - `audience_id` string, required - `enabled` boolean, required: Readers who subscribe through a signup form or the API while this is true start the sequence. With double opt-in, they start when they confirm. - `paused` boolean, required: True when bounces or complaints passed the pause limits. Sends wait until the sequence is enabled again. - `pause_reason` string, nullable, required - `active_readers` integer, required - `completed_readers` integer, required - `steps` WelcomeStep[], required - `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. - … - object: Left column content. Include at least one heading, body, image, or CTA field. - … - object: Left column content. Include at least one heading, body, image, or CTA field. - … - object: Left column content. Include at least one heading, body, image, or CTA field. - … - `right` union, required - object: Right column content. Include at least one heading, body, image, or CTA field. - … - object: Right column content. Include at least one heading, body, image, or CTA field. - … - object: Right column content. Include at least one heading, body, image, or CTA field. - … - object: Right column content. Include at least one heading, body, image, or CTA field. - … - 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)