Before you start, you need:
- your own verified sending domain. The Brudcast trial address has no sending keys. See Email overview.
- a sending key from that domain’s Sending Keys tab, or an API key with the Send Messages permission. See Authentication.
Endpoint
string
required
Bearer followed by your sending key. The send API ignores X-API-Key.string
required
application/jsonExample
Request body
object
required
The sender. The address must be on a domain the key can send from.
object[]
required
At least one recipient, each with an
address (up to 254 characters) and an optional name.object[]
Copy recipients, in the same shape as
to.object[]
Blind-copy recipients, in the same shape as
to. They receive the message but aren’t listed in
its headers.object
Where replies go:
{ "address": "…" }, up to 254 characters.string
required
The subject line. Can’t be empty.
string
The plain-text body. Send
text, html or both. At least one is required.string
The HTML body. Open and click tracking only work on the HTML part.
object[]
Files to attach. See Attachments.
object
Extra headers as name–value pairs. Names up to 78 characters, values up to 998. See
Custom headers.
to and cc can see everyone else in those fields. To send the same email privately to
many people, make one request per recipient, or send a campaign.
Attachments
Base64-encode each file and put it inattachments:
Node.js
Custom headers
Anything inheaders is added to the message, with these exceptions. Brudcast silently removes
these headers because it sets them itself, or because they’d break signing or delivery:
DKIM-Signature,Return-Path,ReceivedContent-Type,MIME-Version,Content-Transfer-Encodingtraceparent,tracestateX-Job-Id
X-Brudcast-. Brudcast reserves them, and its own values replace
yours.
Brudcast adds these headers to every message:
For replies, use the
replyTo field rather than a Reply-To header.
Response
A successful request returns202 Accepted:
boolean
true when the message was queued.string
Email queued for delivery.string
A UUID that identifies this message. Use it to look the message up in the
message log. It also appears in webhook payloads.
202 means queued, not delivered. Delivery to each recipient’s mail server happens next, and you
learn the outcome from the message log or from webhooks.
Which from addresses are allowed
In both cases the domain must be set up in Brudcast. Verify it before sending, or receiving servers
can’t check the DKIM signature and SPF record, and your mail is likely to be rejected or filtered.
What happens after you send
- Suppressed recipients are dropped. Addresses on your organization’s
suppression list are skipped silently. If
every recipient is suppressed, nothing is sent, even though the request returned
202. - Temporary failures are retried. A message deferred by the receiving server is retried up to 3 times.
- Your domain’s tracking settings apply. Open tracking, click tracking and unsubscribe links
follow the settings on the domain’s Settings tab in Channels > Email. They’re off on a new
domain. When a message has several
torecipients, every open and click is credited to the first one.
Errors
See Errors for every message and the fix for each.
Retries and duplicate sends
The send API has no idempotency key. Every accepted request queues a new message, so a request you send twice delivers twice and charges twice. That matters because a202 can be lost on the way back to you — a dropped connection or a client
timeout leaves you unsure whether the message was queued.
For the last case, key the send on something of your own — an order ID, a notification row — and
record the returned
jobId against it before you retry:
- Write your own identifier and a
pendingstate to your database. - Call the send API.
- Store the
jobIdfrom the202against that identifier.
jobId if you captured one; retry
only when you didn’t. This is the same pattern as the contact upsert in
Sync contacts from your app.
Limits
Message status
Look up what happened to a message by its job ID.
Webhooks
Get delivery and bounce events as they happen.
SMTP relay
Send from software that only speaks SMTP.