Developer quickstart

In about ten minutes once your domain is verified, you’ll have a working API key, a sent email and its delivery status. This quickstart crosses two APIs on two hosts, with two different secrets. You’ll collect both:

Steps	Host	Credential
1, 2 and 5	`core-service.prod.brudcast.com`, the platform API	A platform API key, sent as `X-API-Key`
3 and 4	`mailing-service.prod.brudcast.com`, the email send API	A sending key, sent as `Authorization: Bearer`

Both secrets are bk_live_ followed by 64 hex characters, so you can’t tell them apart by looking. Keep them in BRUDCAST_API_KEY and BRUDCAST_SENDING_KEY, the names used throughout this page. See Authentication.

Before you start, you need a terminal with curl, or Node.js, Python or PHP.

Step 0: verify your sending domain

Every step below needs a sending domain of your own, added and verified. Verification waits on a DNS change, which can take a few hours to spread, so start it before anything else.

Add a sending domain. Brudcast generates five DNS records.
Publish them with your DNS provider. See DNS records and DNS by provider.
Verify your domain. It shows Verified once the records resolve.

The Brudcast trial address has no sending keys and no SMTP credentials, so it can’t be used with the send API or SMTP. See Email overview.

Watch the walkthrough

Create an API key

Go to Developers > API Keys and select Create API Key.
Enter a Key Name, for example Quickstart.
Under Permissions, set Sending Domains to Read Sending Domains and Messages to Read Message Log. Leave everything else at No access.
Select Create.
Copy the Secret Key. It starts with bk_live_ and is shown only once.

Store the key in an environment variable rather than in your code:

export BRUDCAST_API_KEY="bk_live_your_api_key"

Make your first platform API call

List your sending domains. This proves the key works and gives you the domain to send from.

curl https://core-service.prod.brudcast.com/api/v1/user/sending-domains \
  -H "X-API-Key: $BRUDCAST_API_KEY"

const response = await fetch(
  "https://core-service.prod.brudcast.com/api/v1/user/sending-domains",
  { headers: { "X-API-Key": process.env.BRUDCAST_API_KEY } },
);

console.log(await response.json());

import os
import requests

response = requests.get(
    "https://core-service.prod.brudcast.com/api/v1/user/sending-domains",
    headers={"X-API-Key": os.environ["BRUDCAST_API_KEY"]},
)

print(response.json())

<?php
$ch = curl_init("https://core-service.prod.brudcast.com/api/v1/user/sending-domains");
curl_setopt_array($ch, [
    CURLOPT_HTTPHEADER => ["X-API-Key: " . getenv("BRUDCAST_API_KEY")],
    CURLOPT_RETURNTRANSFER => true,
]);

echo curl_exec($ch);

Each domain in data has more fields than shown here, and the response also carries meta with pagination details:

{
  "success": true,
  "message": "Sending domains fetched successfully",
  "data": [
    {
      "id": "0b9d7c1e-5f7a-4a57-9a0e-3c2f5d1e8a41",
      "name": "mail.example.com",
      "status": "verified"
    }
  ]
}

Find a domain whose status is verified. You’ll send from an address on it.

Create a sending key

The email send API uses its own credential, bound to one domain.

Go to Channels > Email and open the Domains tab.
Select your domain, then open its Sending Keys tab.
Select Add Sending Key, enter a Description and select Create Key.
Copy the API Secret Key. It’s shown only once.

export BRUDCAST_SENDING_KEY="your_sending_key"

A new key shows provisioning in the Status column for a moment while the send API receives it. Wait until it shows active.

Send an email

Change the from address to one on your verified domain and the to address to an inbox you can check.

curl -X POST https://mailing-service.prod.brudcast.com/api/v1/send \
  -H "Authorization: Bearer $BRUDCAST_SENDING_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": { "name": "Example", "address": "hello@mail.example.com" },
    "to": [{ "name": "Jane", "address": "jane@example.com" }],
    "subject": "My first Brudcast email",
    "text": "It works.",
    "html": "<p>It works.</p>"
  }'

const response = await fetch("https://mailing-service.prod.brudcast.com/api/v1/send", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.BRUDCAST_SENDING_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    from: { name: "Example", address: "hello@mail.example.com" },
    to: [{ name: "Jane", address: "jane@example.com" }],
    subject: "My first Brudcast email",
    text: "It works.",
    html: "<p>It works.</p>",
  }),
});

console.log(response.status, await response.json());

import os
import requests

response = requests.post(
    "https://mailing-service.prod.brudcast.com/api/v1/send",
    headers={"Authorization": f"Bearer {os.environ['BRUDCAST_SENDING_KEY']}"},
    json={
        "from": {"name": "Example", "address": "hello@mail.example.com"},
        "to": [{"name": "Jane", "address": "jane@example.com"}],
        "subject": "My first Brudcast email",
        "text": "It works.",
        "html": "<p>It works.</p>",
    },
)

print(response.status_code, response.json())

<?php
$payload = [
    "from" => ["name" => "Example", "address" => "hello@mail.example.com"],
    "to" => [["name" => "Jane", "address" => "jane@example.com"]],
    "subject" => "My first Brudcast email",
    "text" => "It works.",
    "html" => "<p>It works.</p>",
];

$ch = curl_init("https://mailing-service.prod.brudcast.com/api/v1/send");
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer " . getenv("BRUDCAST_SENDING_KEY"),
        "Content-Type: application/json",
    ],
    CURLOPT_POSTFIELDS => json_encode($payload),
    CURLOPT_RETURNTRANSFER => true,
]);

echo curl_exec($ch);

A 202 Accepted response means Brudcast queued the message:

{
  "status": true,
  "message": "Email queued for delivery",
  "data": { "jobId": "3f1c2a9e-8b7d-4c6e-9a51-2d0e7f4b6c10" }
}

Keep the jobId. It identifies this message everywhere else. Take the value from your own response, not from the example above, and put it in an environment variable. The next step reads it:

export BRUDCAST_JOB_ID="your_job_id"

Check the message status

Look the message up in the message log with your API key from step 1.

curl https://core-service.prod.brudcast.com/api/v1/user/messages/$BRUDCAST_JOB_ID \
  -H "X-API-Key: $BRUDCAST_API_KEY"

const jobId = process.env.BRUDCAST_JOB_ID;
const response = await fetch(
  `https://core-service.prod.brudcast.com/api/v1/user/messages/${jobId}`,
  { headers: { "X-API-Key": process.env.BRUDCAST_API_KEY } },
);

console.log(await response.json());

import os
import requests

job_id = os.environ["BRUDCAST_JOB_ID"]
response = requests.get(
    f"https://core-service.prod.brudcast.com/api/v1/user/messages/{job_id}",
    headers={"X-API-Key": os.environ["BRUDCAST_API_KEY"]},
)

print(response.json())

<?php
$jobId = getenv("BRUDCAST_JOB_ID");
$ch = curl_init("https://core-service.prod.brudcast.com/api/v1/user/messages/" . $jobId);
curl_setopt_array($ch, [
    CURLOPT_HTTPHEADER => ["X-API-Key: " . getenv("BRUDCAST_API_KEY")],
    CURLOPT_RETURNTRANSFER => true,
]);

echo curl_exec($ch);

Once the receiving mail server has answered, each delivery attempt shows up with its outcome:

{
  "success": true,
  "message": "Message fetched successfully",
  "data": {
    "jobId": "3f1c2a9e-8b7d-4c6e-9a51-2d0e7f4b6c10",
    "senderAddress": "hello@mail.example.com",
    "recipients": ["jane@example.com"],
    "deliveryAttempts": [
      {
        "recipient": "jane@example.com",
        "status": "delivered",
        "smtpCode": 250,
        "attemptedAt": "2026-09-11T09:30:12.000Z"
      }
    ],
    "engagementEvents": [],
    "retentionDays": 90
  }
}

A 404 right after sending is normal. The message enters the log only once the receiving server has responded, so wait a few seconds and try again. A 404 that never clears usually means BRUDCAST_JOB_ID holds something other than the jobId your own send returned. See Message status for every field.

What’s next

Instead of polling the message log, have Brudcast call you when something happens. Create a webhook endpoint and subscribe to email.delivered, email.bounced and the other email events.

“Unauthorized access” from the platform API

Why: The key is missing, mistyped, revoked or expired, or your server’s IP address isn’t on the key’s IP allowlist.Fix: Send the full key in X-API-Key, including the bk_live_ prefix. Check the key’s status and IP allowlist in Developers > API Keys.

“This API key is missing the domains:read scope required by this endpoint…”

Why: The key was created without the permission this endpoint needs.Fix: Open the key in Developers > API Keys and edit its Permissions.

“Unauthorized” from the send API

Why: The send API reads only the Authorization header. The key is missing, isn’t prefixed with Bearer , or was deleted or regenerated.Fix: Send Authorization: Bearer followed by the sending key. If you just created or regenerated the key, wait until its status is active.

“From address domain 'x' does not match sending key domain 'y'”

Why: A sending key can only send from the domain it was created on.Fix: Use a from address on that domain, or create a sending key on the other domain.

Email send API

Attachments, Cc and Bcc, custom headers and every error.

Sending keys

The credential the send API needs, and how it differs from an API key.

Webhooks

Get delivery, bounce and engagement events pushed to you.

API keys

Scopes, expiry, IP allowlists and request logs.

Authentication

Which credential works on which surface.

Start here

Sending email

Webhooks

Recipes

Reference

Developer quickstart

Step 0: verify your sending domain

What’s next

Email send API

Sending keys

Webhooks

API keys

Authentication

​Step 0: verify your sending domain

​What’s next

​Related

Email send API

Sending keys

Webhooks

API keys

Authentication

Step 0: verify your sending domain

What’s next

Related