# Broadcasts API > The Broadcasts resource is the public control plane for one-off messages. This guide explains draft management, test sends, and live-send safety. - Human page: https://mailrith.com/developers/broadcasts - Markdown page: https://mailrith.com/developers/broadcasts.md - Category: API Resources - Reading time: 7 min read - Last updated: 2026-07-22 - Related keywords: Broadcasts API, Broadcasts API developer docs, API Resources, API Resources developer docs, Mailrith developer docs, Mailrith public API, Manage Broadcast Drafts, Endpoint Overview, Start and Poll an Asynchronous Send, Handle Preflight, Rate, and Quota Problems, Sending Safety, Email Templates API, Segments API, Webhook Subscriptions API ## AI Agent Notes - Use this page as implementation guidance, then validate exact endpoint fields against the OpenAPI document. - Keep API keys server-side and workspace-scoped unless a guide explicitly says otherwise. - Do not invent privacy, consent, or lawful-basis evidence. Send only fields that appear in the OpenAPI schema for the endpoint you are using. ## What this guide covers Create Broadcast drafts, send test emails, and control live Broadcast sends with the Broadcasts resource permission. ## Manage Broadcast Drafts Broadcasts are one-off messages sent to Subscribers. The public Broadcasts API lets integrations create drafts, inspect existing Broadcasts, update their details, send test emails, and start a live send only when the Broadcast is ready. Creating or updating a Broadcast does not send it. The `broadcasts:write` resource permission covers draft, test, schedule, send, stop, and delete operations. Limit the tools available to an agent when its task should use only part of that lifecycle. Use the API to prepare Broadcasts and call the send operation only when the requested task includes contacting real Subscribers. 1. Create the broadcast as a draft. 2. Set the subject, preview text, body, and any required Broadcast metadata. 3. Select or store the segment or filter rules that choose the intended subscribers, then ask a user to review the subscribers in [Broadcasts](https://mailrith.com/docs/broadcasts.md) before live sending. 4. Send a test email with the test endpoint. 5. If your integration manages approvals, record the reviewer and approval state in your own system. 6. Call the live send endpoint only after the subscribers, content, sender, and send timing are approved. 7. After sending, read the broadcast results from Mailrith. Do not assume the send completed instantly. - Create Broadcasts as drafts when you migrate messages or prepare Broadcast content. - Use test sends before live sends so reviewers can inspect the rendered email. - Use live send endpoints only after your workflow confirms the subscribers, subject, content, and compliance requirements. - Store the returned Broadcast ID if another system must link its records to the Mailrith Broadcast. ## Endpoint Overview Collection and item endpoints manage broadcast records. Use these endpoints to list, create, inspect, update, and delete broadcasts. `POST /v1/broadcasts/{broadcast_id}/test` sends a test email to a reviewer. Use this endpoint in review workflows, but do not send test emails to large or uncontrolled lists. `GET /v1/broadcasts/{broadcast_id}/preflight` checks the current Subscriber estimate, provider capacity, sender setup, and blocking issues. `POST /v1/broadcasts/{broadcast_id}/send` accepts the live send asynchronously and returns `202 Accepted` with a run ID. In internal tools and agent workflows, require explicit approval before calling this endpoint. `GET /v1/broadcasts/{broadcast_id}/progress` returns bounded progress. `GET /v1/broadcasts/{broadcast_id}/delivery-errors` returns cursor-paginated permanent failures and unknown results. `POST /v1/broadcasts/{broadcast_id}/cancel` requests cancellation for work that has not reached the provider. It cannot recall provider-accepted email. Related OpenAPI operation groups: - Broadcasts **Send a Broadcast Test Email** ```bash curl -X POST https://api.mailrith.com/v1/broadcasts/broadcast_123/test \ -H "Authorization: Bearer mrk_example_secret_key" \ -H "Idempotency-Key: broadcast-123-test-1" \ -H "Content-Type: application/json" \ -d '{ "recipient_email": "reviewer@example.com" }' ``` ## Start and Poll an Asynchronous Send A `202 Accepted` response means Mailrith saved the send request and queued durable preparation. It does not mean every email was delivered or accepted by the provider. Store `run_id`, then poll the progress endpoint until `terminal` is `true`. Use an `Idempotency-Key` on send and cancellation requests. If your connection drops before you receive the response, repeat the same method, path, body, and key. Do not create a new key for an uncertain retry. You can call the preflight endpoint when you want a readiness diagnostic before sending. A successful check returns a short-lived `send_proof`, which you may pass unchanged as `preflight_proof`. Preflight is optional: without a valid proof, Mailrith still creates the durable run immediately, then calculates the exact Subscriber total and checks provider readiness in the background before delivery. Poll once after 5 seconds, then use 10-second intervals while the send is changing. After several unchanged responses, increase the interval to 30 seconds. Stop when `terminal` is `true`. Always honor `Retry-After` after a `429` response. Cancellation returns `202 Accepted`. A `status` of `canceling` means remaining work is stopping. A `status` of `canceled` means cancellation already finished. `changed` says whether this request changed durable state. If `recovery_pending` is `true`, the request is saved and recovery will continue it even though the immediate Queue wake could not be sent. - `phase` describes preparing, sending, paused, canceling, sent, sent with errors, canceled, or failed work. - `materialized` is the number of prepared Subscriber deliveries. `accepted` is the number accepted by the provider. - `retrying` is work waiting for a safe retry. `permanent_failed` will not be retried automatically. - `unknown` means Mailrith cannot prove whether the provider accepted the email. Do not automatically retry unknown results. - `provider` identifies the selected email service. `estimated_completion_basis` is `provider-quota` when known quota windows are included and `current-rate` when the estimate uses only the current sending speed. - `percent_complete`, `effective_rate`, `estimated_completion`, `pause_reason`, and `next_retry_at` can change as provider capacity changes. - The compatible Broadcast status remains `running` while active and `completed` after terminal processing. Use progress `phase` and outcome counts for the detailed result. - Cancellation returns `broadcast_send_not_found` when no durable send exists, `broadcast_cancel_finalization_started` or `broadcast_cancel_already_finished` when the run can no longer be canceled, and `broadcast_cancel_concurrent_update` when another control action won the state change. Read the latest progress before deciding what to do next. **Start a Broadcast** ```bash curl -X POST https://api.mailrith.com/v1/broadcasts/broadcast_123/send \ -H "Authorization: Bearer mrk_example_secret_key" \ -H "Idempotency-Key: broadcast-123-send-1" \ -H "Content-Type: application/json" \ -d '{}' ``` **Read Progress and Delivery Errors** ```bash curl https://api.mailrith.com/v1/broadcasts/broadcast_123/progress \ -H "Authorization: Bearer mrk_example_secret_key" curl "https://api.mailrith.com/v1/broadcasts/broadcast_123/delivery-errors?limit=100" \ -H "Authorization: Bearer mrk_example_secret_key" ``` **Request Cancellation Safely** ```bash curl -X POST https://api.mailrith.com/v1/broadcasts/broadcast_123/cancel \ -H "Authorization: Bearer mrk_example_secret_key" \ -H "Idempotency-Key: broadcast-123-cancel-1" ``` ## Handle Preflight, Rate, and Quota Problems Read every `blocking_issues` item before starting. Each item includes a stable code, a plain-language message, and a resolution. Run preflight again after correcting the connection or sender setup because Subscriber counts and provider capacity can change. A send can return a conflict when the Broadcast changed after preflight. Fetch a new preflight instead of resubmitting stale proof data. - `broadcast_provider_quota_unavailable`: Mailrith could not read the saved connection settings. Reconnect the named email service. - `broadcast_provider_production_access_required`: the provider account cannot send production volume yet. - `broadcast_connection_unavailable`: the selected connection is disabled, deleted, unlinked, unsupported, or incomplete. - `broadcast_connection_unhealthy`: Mailrith could not reach the provider during the connection check. - `broadcast_sender_unverified`: the provider did not confirm the selected sending address or domain. - `broadcast_no_recipients`: no active Subscribers match the saved selection. - `broadcast_not_sendable`: the Broadcast is no longer in a state that can start a send. - A provider pause or quota wait during delivery appears in `pause_reason` and `next_retry_at`. Continue polling; do not create another Broadcast send. - A `429` response is an API request-rate limit. Wait for `Retry-After`; it is separate from the provider's email send rate. ## Sending Safety A Broadcast send can contact real Subscribers. Give the Broadcasts Work Profile only to workflows that need to manage the complete Broadcast lifecycle. For a preparation-only AI workflow, restrict the client to draft and preflight tools. A credential with `broadcasts:write` can send without a second Mailrith approval, so the agent should confirm the selected Subscribers and run a test before it starts delivery. When a send fails, keep the error code, Broadcast ID, and run ID in your logs. Do not retry live sends blindly. Reuse the same idempotency key when a response is lost, and never automatically retry an unknown delivery outcome. - Confirm that the workspace key points to the intended workspace before creating or sending Broadcasts. - Confirm that the subscribers or segment are correct before calling the live send endpoint. - Send a test to a controlled reviewer address. - Use a stable idempotency key for the send request, then follow the returned run until it reaches a final state. ## Related Guides - [Email Templates API](https://mailrith.com/developers/email-templates.md): The email templates resource supports migrations, governance, and external template sync. This guide explains when to use templates, how to preserve structured editor content, and how to keep template names and descriptions useful for workspace users. - [Segments API](https://mailrith.com/developers/segments.md): The segments API supports saved segment definitions, imported subscriber rules, and previews for unsaved logic. This guide explains how segments behave, when to save segments, and why preview is the safest step before using complex subscriber rules. - [Webhook Subscriptions API](https://mailrith.com/developers/webhook-subscriptions.md): Webhook subscriptions let external systems receive Mailrith events for syncs, dashboards, fulfillment, and audit trails. This guide explains when to use webhooks, how to manage subscriptions, why you must store the signing secret immediately, and how receivers should verify and deduplicate deliveries.