Broadcasts API

Manage One-Off Campaign Drafts

1. Create the broadcast as a draft.
2. Set the subject, preview text, body, and any required campaign 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 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 campaigns or prepare campaign work for review.
• 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 approvals or audit records to the Mailrith campaign.

Endpoint Overview

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

• 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.
• 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.

curl https://api.mailrith.com/v1/broadcasts/broadcast_123/preflight \
  -H "Authorization: Bearer mrk_example_secret_key"

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 '{
    "confirmation": {
      "workspace_id": "workspace_123",
      "subject": "April Launch",
      "recipient_estimate": 1000000,
      "connection_id": "connection_123",
      "estimated_duration_seconds": 2000
    }
  }'

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"

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

• broadcast_provider_quota_unavailable: Mailrith could not verify safe provider capacity. Check the connection or reviewed provider limits.
• broadcast_provider_production_access_required: the provider account cannot send production volume yet.
• broadcast_provider_daily_quota_insufficient: the remaining safe daily quota is smaller than the selected Subscriber count.
• broadcast_high_volume_sends_paused: an administrator has temporarily blocked new high-volume starts.
• broadcast_production_approval_required: the workspace does not have a current production high-volume approval. Contact Mailrith support.
• broadcast_production_connection_not_approved: choose the delivery connection named in the workspace approval, or ask Mailrith support to review the new connection.
• broadcast_production_approval_expired: the workspace approval has expired. Ask Mailrith support to renew it with current evidence.
• broadcast_production_canary_limit_exceeded: the current Subscriber estimate is above the approved canary checkpoint. Reduce the selection or complete the next review.
• 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_event_webhook_missing: provider delivery event tracking is not configured for this connection.
• 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

• Confirm that the workspace key points to the intended workspace before creating or sending campaigns.
• Confirm that the subscribers or segment are correct before calling the live send endpoint.
• Send a test to a controlled reviewer address.
• Log the person, system, or rule that approved the live send in your own system.