Audiences & broadcasts

Group the people you email into an audience, then send to all of them with one call. Dairo fans the broadcast out in the background and skips anyone who previously reported your mail as spam. Audiences are built for opted-in sending — onboarding cohorts, customer announcements, internal notices — not cold outreach. Reading audiences uses the audiences:read scope; creating, adding members, and deleting use audiences:write. Sending a broadcast is a send like any other — it needs messages:send.

Create an audience

POST /v1/audiences takes a name (up to 120 characters) and an optional description.

curl -X POST https://api.dairo.app/v1/audiences \
  -H "Authorization: Bearer $DAIRO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Beta announcements" }'

const audience = await dairo.audiences.create({ name: "Beta announcements" });
console.log(audience.list.id);

audience = dairo.audiences.create(name="Beta announcements")
print(audience.list.id)

Tool: manage_audiences  (scope audiences:write, confirm required)
Args: { "action": "create", "name": "Beta announcements", "confirm": true }

{
  "list": {
    "object": "audience",
    "id": "aud_123",
    "name": "Beta announcements",
    "status": "active",
    "memberCount": 0,
    "createdAt": "2026-06-12T10:00:00Z",
    "updatedAt": "2026-06-12T10:00:00Z"
  }
}

Add members

POST /v1/audiences/{audienceId}/members takes up to 2,000 members per request. Each member is exactly one of:

a raw handle — an email address, with an optional name, or
a contactId — a contact whose primary email address becomes the member’s address. An unknown contact is a 404; a contact without an email handle is a 422.

Members are upserted by address: re-adding someone updates their name and metadata instead of creating a duplicate. The response reports how many members the request imported.

curl -X POST https://api.dairo.app/v1/audiences/aud_123/members \
  -H "Authorization: Bearer $DAIRO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "members": [ { "handle": "ada@example.com", "name": "Ada Lovelace" } ] }'

await dairo.audiences.addMembers("aud_123", {
  members: [{ handle: "ada@example.com", name: "Ada Lovelace" }],
});

dairo.audiences.add_members(
    "aud_123",
    [{"handle": "ada@example.com", "name": "Ada Lovelace"}],
)

Tool: manage_audiences  (scope audiences:write, confirm required)
Args: { "action": "addMembers", "audienceId": "aud_123", "members": [ { "handle": "ada@example.com", "name": "Ada Lovelace" } ], "confirm": true }

{ "audienceId": "aud_123", "imported": 1 }

Inspect an audience

List your audiences with GET /v1/audiences, or fetch one to see its active members.

curl https://api.dairo.app/v1/audiences \
  -H "Authorization: Bearer $DAIRO_API_KEY"

curl https://api.dairo.app/v1/audiences/aud_123 \
  -H "Authorization: Bearer $DAIRO_API_KEY"

const audiences = await dairo.audiences.list();
const detail = await dairo.audiences.get("aud_123");
console.log(detail.members.length);

audiences = dairo.audiences.list()
detail = dairo.audiences.get("aud_123")
print(len(detail.members))

Send a broadcast

POST /v1/audiences/{audienceId}/send emails every active member from the inbox you name. The body takes the same inboxId, subject, body, and attachments fields as a single send — exactly one of text, html, react, or a stored template — but no to, because the recipients come from the audience. Scheduling (sendAt), replyTo, custom headers, and tags are not available on broadcasts. A broadcast is asynchronous. Dairo validates the request and pins the message once — a stored template resolves at submit, so a bad template or variable is a 400 now, not a failure mid-fan-out — then returns 202 and delivers to each member in the background:

{
  "object": "broadcast",
  "id": "bcast_9f8c2a1b4e7d",
  "audienceId": "aud_123",
  "status": "queued"
}

Each member’s delivery becomes its own outbound message, so bounces and complaints surface per recipient in delivery tracking.

curl -X POST https://api.dairo.app/v1/audiences/aud_123/send \
  -H "Authorization: Bearer $DAIRO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: beta-open-2026-06" \
  -d '{
        "inboxId": "inbox_7c9e6679",
        "subject": "We are opening the beta",
        "html": "<p>You are in. Here is how to get started…</p>"
      }'

const result = await dairo.audiences.send("aud_123", {
  inboxId: "inbox_7c9e6679",
  subject: "We are opening the beta",
  html: "<p>You are in. Here is how to get started…</p>",
  idempotencyKey: "beta-open-2026-06",
});
console.log(result.audienceId);

result = dairo.audiences.send(
    "aud_123",
    inbox_id="inbox_7c9e6679",
    subject="We are opening the beta",
    html="<p>You are in. Here is how to get started…</p>",
    idempotency_key="beta-open-2026-06",
)
print(result.audience_id)

Tool: send_broadcast  (scope messages:send)
Args: { "action": "send", "audienceId": "aud_123", "inboxId": "inbox_7c9e6679", "subject": "We are opening the beta", "html": "…" }

Members who reported your mail as spam are skipped. Every broadcast leaves them out by default, which protects your sender reputation; they are only contacted if you deliberately pass ignoreComplaints: true. See Land in the inbox.

Retrying a broadcast is safe. A re-sent request with the same Idempotency-Key — or an identical request with no key at all — de-duplicates per recipient instead of emailing the whole audience twice. To deliberately send the same content to the same audience again, pass a new key. See Retries & idempotency.

Delete an audience

Deleting an audience archives it so it can no longer be sent to.

curl -X DELETE https://api.dairo.app/v1/audiences/aud_123 \
  -H "Authorization: Bearer $DAIRO_API_KEY"

await dairo.audiences.delete("aud_123");

dairo.audiences.delete("aud_123")

Send responsibly

Only add people who opted in. Importing scraped or purchased addresses generates spam complaints and damages your domain’s reputation for every inbox you send from.
Review the copy before a large send. Especially for agent-written copy, have a person read the message before it goes to everyone.
Prune addresses that keep bouncing. Watch each broadcast’s bounces in delivery tracking and remove repeat offenders to keep the audience healthy.

Next steps

Templates — write one email and reuse it across every broadcast.
Webhooks — get per-recipient delivery events pushed to your app.
API reference — every audiences endpoint, with copy-paste requests.

Get started

Sending

Channels

Contacts

Files & storage

Send physical mail

Phone

Receiving

Domains & deliverability

Events & webhooks

Guides

Foundations

For AI agents

Scale & compliance

Audiences & broadcasts

Create an audience

Add members

Inspect an audience

Send a broadcast

Delete an audience

Send responsibly

Next steps

​Create an audience

​Add members

​Inspect an audience

​Send a broadcast

​Delete an audience

​Send responsibly

​Next steps

Create an audience

Add members

Inspect an audience

Send a broadcast

Delete an audience

Send responsibly

Next steps