--- title: "POST /v1/workspaces/{workspaceId}/broadcasts" method: POST path: "/v1/workspaces/{workspaceId}/broadcasts" --- # POST /v1/workspaces/{workspaceId}/broadcasts `POST /v1/workspaces/{workspaceId}/broadcasts` ## Request - Base URL: `https://api.bangermail.com` - URL: `https://api.bangermail.com/v1/workspaces/{workspaceId}/broadcasts` - Auth: HTTP bearer ## Headers - `Idempotency-Key` string, required ## Request body - object - `name` string, required - `mailbox_id` string, uuid: Existing sender address. Omit to use the onboarding sender, then an active custom mailbox, then hosted. - `template_id` string, uuid - `audience` object - `all_subscribed` boolean - `contact_ids` string[] - `list_ids` string[] - `segment_ids` string[] - `subject_variants` string[] - `selected_subject_variant` integer - `expires_after_seconds` integer: Discard unsent recipients after this many seconds from the scheduled time; defaults to seven days. - `content_overrides` object ## Response `200` Canonical read-back or idempotent receipt. Provider acceptance is sent; delivered requires a delivery event and does not prove inbox placement. - object - `data` object, required - `id` string, uuid, required - `product_id` string, uuid, required - `name` string, required - `mailbox_id` string, uuid - `template_id` string, uuid, nullable - `managed_content_id` string, uuid, nullable - `managed_source_revision_id` string, uuid, nullable - `managed_publication_id` string, uuid, nullable - `managed_locales_snapshot` string[] - `expires_after_seconds` integer, nullable - `status` string - `version` integer, required - `subject_variants` string[] - `selected_subject_variant` integer - `content_overrides` object - `audience_query` CampaignAudience: Select all subscribed contacts or at least one nonempty contact_ids, list_ids, or segment_ids list. - `all_subscribed` boolean - `contact_ids` string[] - `list_ids` string[] - `segment_ids` string[] - `audience_frozen_at` string, date-time, nullable - `audience_recipient_count` integer, nullable - `audience_snapshot_sha256` string, nullable - `audience_snapshot_campaign_version` integer, nullable - `scheduled_at` string, date-time, nullable - `started_at` string, date-time, nullable - `completed_at` string, date-time, nullable - `created_at` string, date-time - `updated_at` string, date-time - `archived_at` string, date-time, nullable - `stats` object - `broadcast_id` string, uuid, required - `sender_address` string, nullable, required - `sending_blocker` object, nullable, required - `code` string, required - `message` string, required - `design` object, nullable, required - `id` string, uuid - `product_id` string, uuid - `name` string - `subject` string - `body_text` string - `content` object - `slots` TemplateSlot[] - `key` string, required - `label` string - `type` 'text' | 'paragraph' | 'url' | 'image' - `help` string - `status` 'active' | 'archived' - `origin` 'person' | 'agent' | 'starter' | 'import' - `created_by_actor_id` string, nullable - `campaign_id` string, uuid, nullable - `message_kind` string - `starter_id` string, nullable - `starter_version` integer, nullable - `version` integer - `created_at` string, date-time - `updated_at` string, date-time - `body_html_url` string, uri - `body_html` string, nullable - `body_html_b2_key` string, nullable - `managed_content` object, nullable, required - `id` string, uuid, required - `name` string, required - `version` integer, required - `review_required` boolean, required - `draft_revision_id` string, uuid, nullable - `submitted_revision_id` string, uuid, nullable - `approved_revision_id` string, uuid, nullable - `published_revision_id` string, uuid, nullable - `published_publication_id` string, uuid, nullable - `source_revision` object, required - `id` string, uuid, required - `content_id` string, uuid, required - `revision` integer, required - `source_locale` string, required - `configured_locales` string[], required - `fallback_locale` string, nullable, required - `localization_policy` object, required: A Journey email goes out only in the person's own language: it waits for their translation, about a minute for receipts, codes and security notices and up to a day for other email, and is not sent if the translation is not ready by then. - `manual_review` boolean - `source` object, required - `subject` string, required - `preheader` string - `body_text` string: Accepted for source compatibility; rendered plain text derives from final HTML. - `body_html` string, required - `layout` string: Must contain one {{ content }} slot. - `variants` object: Optional source versions. Every version is translated automatically in the same revision. - `variables` object, required - `source_messages` object, required - `layout_id` string, uuid, nullable, required - `layout_revision_id` string, uuid, nullable, required - `samples` object, required - `restored_from_revision_id` string, uuid, nullable, required - `translations` object[], required - `source_revision_id` string, uuid, required - `locale` string, required - `strings` object, required - `provenance` 'supplied' | 'generated' | 'reviewed', required - `status` 'ready' | 'needs_review', required - `translation_jobs` object[] - `published_source_revision` ManagedSourceRevision, required - `id` string, uuid, required - `content_id` string, uuid, required - `revision` integer, required - `source_locale` string, required - `configured_locales` string[], required - `fallback_locale` string, nullable, required - `localization_policy` object, required: A Journey email goes out only in the person's own language: it waits for their translation, about a minute for receipts, codes and security notices and up to a day for other email, and is not sent if the translation is not ready by then. - `manual_review` boolean - `source` object, required - `subject` string, required - `preheader` string - `body_text` string: Accepted for source compatibility; rendered plain text derives from final HTML. - `body_html` string, required - `layout` string: Must contain one {{ content }} slot. - `variants` object: Optional source versions. Every version is translated automatically in the same revision. - `variables` object, required - `source_messages` object, required - `layout_id` string, uuid, nullable, required - `layout_revision_id` string, uuid, nullable, required - `samples` object, required - `restored_from_revision_id` string, uuid, nullable, required - `subject` string, nullable, required - `sender_mailbox` object, nullable, required - `id` string, uuid, required - `address` string, required - `display_name` string, required - `status` string, required - `reply_mailbox` object, nullable, required - `id` string, uuid, required - `address` string, required - `display_name` string, required - `status` string, required - `design_version` integer, nullable, required - `audience` CampaignAudience, required: Select all subscribed contacts or at least one nonempty contact_ids, list_ids, or segment_ids list. - `all_subscribed` boolean - `contact_ids` string[] - `list_ids` string[] - `segment_ids` string[] - `replayed` boolean, required - `preview` RenderedEmail - `subject` string, required - `preheader` string - `html` string, required - `text` string, required - `locale` string, required - `direction` 'ltr' | 'rtl', required - `warnings` string[] - `translation_jobs` string[], required ## Other responses - `400`: Invalid input or missing operating product. - `403`: Existing OAuth scope or product boundary denied. - `409`: Stale version or idempotency conflict. - `422`: Consent, suppression, personalization, or readiness blocker. --- [API](https://skmtc.dev/bangermail/apis/banger-api.md) · [All operations](https://skmtc.dev/bangermail/apis/banger-api/llms.txt) · [OpenAPI document](https://skmtc.dev/bangermail/apis/banger-api/revisions/a149909267f9?raw)