Command Palette

Search for a command to run...

Guide

Sending Broadcasts

Learn how to send bulk emails to your audiences using broadcasts. Perfect for newsletters, announcements, and marketing campaigns.

Newsletters

Regular updates

Audiences

Target subscribers

Scheduling

Send later

Analytics

Track engagement

What are Broadcasts?

Broadcasts allow you to send a single email to multiple recipients in an audience at once. Unlike transactional emails sent one-by-one, broadcasts are designed for:

  • Newsletters - Regular updates to subscribers
  • Product announcements - New features, releases
  • Marketing campaigns - Promotions, offers
  • Company updates - News, events, milestones

Note: Broadcasts are sent only to subscribed contacts in your audience. Unsubscribed contacts are automatically excluded.

Prerequisites

Before sending broadcasts, you need:

1

Verified Domain

Set up and verify your sending domain with DNS records.

Domain verification guide →
2

Audience with Contacts

Create an audience and add subscribed contacts.

Audiences guide →
3

API Key

Generate an API key with send permissions.

API Keys reference →

Creating a Broadcast

Step 1: Create the broadcast

Create a broadcast with your email content and target audience:

cURL
curl -X POST https://www.unosend.co/api/v1/broadcasts \
  -H "Authorization: Bearer un_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "December Newsletter",
    "from": "Newsletter <newsletter@yourcompany.com>",
    "subject": "🎄 December Updates & Holiday Hours",
    "audience_id": "aud_abc123",
    "html": "<h1>Hello!</h1><p>Here are our December updates...</p>"
  }'

Step 2: Review the response

The broadcast is created in draft status:

200 OK
{
  "success": true,
  "data": {
    "id": "brd_xyz789",
    "name": "December Newsletter",
    "from": "Newsletter <newsletter@yourcompany.com>",
    "subject": "🎄 December Updates & Holiday Hours",
    "status": "draft",
    "audience_id": "aud_abc123",
    "total_recipients": 1250,
    "scheduled_at": null,
    "created_at": "2024-12-01T10:00:00.000Z"
  }
}

Important: The total_recipients shows how many subscribed contacts will receive this broadcast. Review this number before sending!

Using Templates

Instead of inline HTML, you can use a pre-built template:

cURL
curl -X POST https://www.unosend.co/api/v1/broadcasts \
  -H "Authorization: Bearer un_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "December Newsletter",
    "from": "Newsletter <newsletter@yourcompany.com>",
    "subject": "🎄 December Updates & Holiday Hours",
    "audience_id": "aud_abc123",
    "template_id": "tpl_newsletter_v2"
  }'

Learn more about templates in the Templates Guide.

Scheduling Broadcasts

Schedule a broadcast for future delivery by adding scheduled_at:

cURL
curl -X POST https://www.unosend.co/api/v1/broadcasts \
  -H "Authorization: Bearer un_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "New Year Announcement",
    "from": "Team <team@yourcompany.com>",
    "subject": "🎉 Happy New Year from Our Team!",
    "audience_id": "aud_abc123",
    "html": "<h1>Happy New Year!</h1><p>Wishing you all the best...</p>",
    "scheduled_at": "2025-01-01T00:00:00.000Z"
  }'

Response

200 OK
{
  "success": true,
  "data": {
    "id": "brd_newyear",
    "status": "scheduled",
    "scheduled_at": "2025-01-01T00:00:00.000Z",
    ...
  }
}

Broadcast Status

Broadcasts go through several statuses:

StatusDescription
draftBroadcast created but not yet sent or scheduled
scheduledBroadcast scheduled for future delivery
sendingBroadcast is currently being sent
sentAll emails have been sent
pausedBroadcast sending has been paused
cancelledBroadcast was cancelled before completion

Managing Broadcasts

List all broadcasts

cURL
curl https://www.unosend.co/api/v1/broadcasts \
  -H "Authorization: Bearer un_your_api_key"

Get broadcast details

cURL
curl https://www.unosend.co/api/v1/broadcasts/brd_xyz789 \
  -H "Authorization: Bearer un_your_api_key"

Update a draft broadcast

cURL
curl -X PATCH https://www.unosend.co/api/v1/broadcasts/brd_xyz789 \
  -H "Authorization: Bearer un_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "subject": "Updated: December Newsletter 📬"
  }'

Delete a broadcast

Only draft broadcasts can be deleted:

cURL
curl -X DELETE https://www.unosend.co/api/v1/broadcasts/brd_xyz789 \
  -H "Authorization: Bearer un_your_api_key"

Best Practices

Test before sending

Send a test email to yourself before broadcasting to your entire audience. Check formatting, links, and personalization.

Use clear subject lines

Write compelling subject lines that accurately describe the content. Avoid spam trigger words.

Include unsubscribe link

Unosend automatically adds unsubscribe links to broadcasts. Make sure they're visible in your template.

Monitor delivery metrics

Check open rates, click rates, and bounces after sending. Use the Events API to track engagement.

Respect time zones

Schedule broadcasts at optimal times for your audience. Consider their time zones for better engagement.