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 send actions should be treated as high-impact operations in integrations and agents.
7 min read
Manage One-Off Campaign Drafts
Broadcasts are one-off campaigns sent to an audience. The public broadcasts API lets integrations create drafts, inspect existing broadcasts, update campaign details, send test emails, and explicitly send a broadcast when it is ready.
Creating or updating a broadcast does not send it. Sending is a separate action because it can reach real subscribers. This separation makes it safer to build migrations, campaign operations tools, and external approval workflows.
Use the API to prepare campaign records, but keep the human review process clear when the campaign affects a real audience.
- Create the broadcast as a draft.
- Set subject, preview text, body, and any required campaign metadata.
- Select or store the intended audience definition, but ask a user to review the audience in Broadcasts before live sending.
- Send a test email with the test endpoint.
- Record the reviewer and approval state in your own system if the integration manages approvals.
- Call the live send endpoint only after the audience, content, sender, and timing are approved.
- After sending, read broadcast results from Mailrith rather than assuming the send completed instantly.
- Create broadcasts as drafts when importing campaigns or preparing work for review.
- Use test sends before live sends so reviewers can inspect the rendered email.
- Use live send endpoints only after your workflow has confirmed the audience, subject, content, and compliance requirements.
- Store the returned broadcast ID if another system needs to link approvals or audit records to the Mailrith campaign.
Endpoint Overview
Collection and item endpoints manage the broadcast record. Use them for listing, creating, inspecting, updating, and deleting broadcasts.
POST /v1/broadcasts/{broadcast_id}/test sends a test email to a reviewer. Use this endpoint freely in review workflows, but still avoid sending test emails to large or uncontrolled lists.
POST /v1/broadcasts/{broadcast_id}/send is the live-send action. Put this behind explicit approval in internal tools and agent workflows.
/v1/broadcasts List broadcasts
Returns broadcast drafts, scheduled sends, active sends, and completed sends.
View Schema /v1/broadcasts Create a broadcast
Creates a broadcast draft or scheduled broadcast in the authenticated workspace.
View Schema /v1/broadcasts/{broadcast_id} Get a broadcast
Returns a broadcast draft, scheduled send, active send, or completed send.
View Schema /v1/broadcasts/{broadcast_id} Update a broadcast
Updates a broadcast draft or scheduled send in place.
View Schema /v1/broadcasts/{broadcast_id} Delete a broadcast
Deletes an existing broadcast from the authenticated workspace.
View Schema /v1/broadcasts/{broadcast_id}/send Send a broadcast now
Launches immediate delivery for a broadcast draft or scheduled send.
View Schema /v1/broadcasts/{broadcast_id}/test Send a broadcast test email
Sends a test message for an existing broadcast to a single recipient.
View Schemacurl -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 in your integration design.
For AI agents and workflow tools, separate draft creation from send approval. Let the tool prepare the draft, summarize the audience, 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 unless your integration has confirmed the previous attempt did not already begin sending.
- Confirm the workspace key points to the intended workspace before creating or sending campaigns.
- Confirm the audience or segment before calling the live send endpoint.
- Send a test to a controlled reviewer address.
- Log who or what approved the live send in your own system.
Need Help Shipping an Integration?
Reach the Mailrith team if you need help planning a sync, validating a webhook flow, or troubleshooting a request.
Related Guides
Manage reusable email templates, structured editor content, and approved layout libraries.
Manage saved audience rules and preview unsaved segment definitions before saving or sending.
Create signed event subscriptions for CRMs, dashboards, audits, and workflow systems.