# Broadcasts API



> The broadcasts resource is the public campaign control plane for one-off messages. This guide explains draft management, test sends, live-send safety, and why integrations and agents should treat send actions as high-impact operations.



- 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-06-13

- Related keywords: Broadcasts API, Broadcasts API developer docs, API Resources, API Resources developer docs, Mailrith developer docs, Mailrith public API, Manage One-Off Campaign Drafts, Endpoint Overview, 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 campaign drafts, send test emails, and require deliberate approval before live broadcast sends.



## Manage One-Off Campaign Drafts

Broadcasts are one-off campaigns sent to subscribers. The public broadcasts API lets integrations create drafts, inspect existing broadcasts, update campaign details, send test emails, and send a broadcast only when the broadcast is ready.

Creating or updating a broadcast does not send the broadcast. Sending is a separate action because a live send can reach real subscribers. This separation helps you build safer migrations, campaign operations tools, and external approval workflows.

Use the API to prepare campaign records. When a campaign affects real subscribers, make the human review steps clear before live sending.

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](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 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

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.

`POST /v1/broadcasts/{broadcast_id}/send` starts the live send. In internal tools and agent workflows, require explicit approval before calling this endpoint.

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"
  }'
```

## Sending Safety

A broadcast send can contact real subscribers. Treat send permission as a high-impact permission when you design your integration.

For AI agents and workflow tools, keep draft creation separate from send approval. Let the tool prepare the draft, summarize the subscribers, and send a test. Then require a person or trusted approval rule before live sending.

When a send fails, keep the full error code and broadcast ID in your logs. Do not retry live sends blindly. Retry only after your integration confirms that the previous attempt did not already begin sending.

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



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