Skip to main content
Send one email per request, as JSON, from any sending domain you’ve verified. Brudcast queues it and returns a job ID straight away.
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/json

Example

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.
Everyone in 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 in attachments:
Node.js
The whole JSON body must be under 10 MB. Base64 makes a file about a third larger, so that leaves room for roughly 7.5 MB of original files in one message.

Custom headers

Anything in headers 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, Received
  • Content-Type, MIME-Version, Content-Transfer-Encoding
  • traceparent, tracestate
  • X-Job-Id
Don’t use names that start with 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 returns 202 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 to recipients, 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 a 202 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:
  1. Write your own identifier and a pending state to your database.
  2. Call the send API.
  3. Store the jobId from the 202 against that identifier.
If step 2 or 3 fails, you still have the row. Before retrying, look the message up with Message status using the 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.
Don’t retry a 202 you already received. The message is queued, and delivery has not failed — it simply hasn’t finished. Watch its status instead.

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.