API reference
A small, predictable REST API for sending transactional email and reading your message log.
The Buzzmark API is organised around a few REST endpoints that return JSON. The base URL is
https://api.buzzmarkapp.com. All requests must be made over HTTPS.
Authentication
Every request authenticates with a Hive API token - generate one on a hive’s page in the dashboard, where it is shown exactly once. Send it in a header, either way:
X-Buzzmark-Server-Token: bzm_srv_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
# or
Authorization: Bearer bzm_srv_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxThe same token is the password for SMTP sending. Keep it secret; rotate it from the dashboard if it leaks.
Errors
Errors use a industry standard-style envelope so existing tooling feels familiar:
{ "ErrorCode": 10, "Message": "Invalid or missing server API token." }| ErrorCode | Meaning |
|---|---|
| 0 | OK |
| 10 | Invalid / missing API token |
| 300 | Invalid request (validation) |
| 401 | From domain is not a verified domain on the account |
| 406 | Recipient is on the suppression list |
| 701 | Unknown message / inbound address |
Send a single email
From and To are required; provide at least one of HtmlBody / TextBody. The From domain must be a verified domain on the account (unless sender enforcement is disabled).
{
"From": "Sales <hello@yourdomain.com>",
"To": "customer@example.com",
"Cc": "cc@example.com",
"Bcc": "bcc@example.com",
"ReplyTo": "support@yourdomain.com",
"Subject": "Welcome aboard",
"HtmlBody": "<h1>Hi!</h1>",
"TextBody": "Hi!",
"Tag": "welcome",
"Headers": [{ "Name": "X-Custom", "Value": "abc" }],
"Metadata": { "user_id": "42" },
"MessageStream": "outbound"
}Example request:
curl -X POST https://api.buzzmarkapp.com/api/email \
-H "X-Buzzmark-Server-Token: bzm_srv_..." \
-H "Content-Type: application/json" \
-d '{
"From": "hello@yourdomain.com",
"To": "customer@example.com",
"Subject": "Welcome aboard",
"HtmlBody": "<h1>Hi!</h1>"
}'Response:
{
"To": "customer@example.com",
"SubmittedAt": "2026-05-31T22:28:43+00:00",
"MessageID": "f5ab446c-18ad-4db4-b747-8e1ba70ec72d",
"ErrorCode": 0,
"Message": "OK"
}The MessageID is an opaque UUID; use it to look the message up or to correlate webhook events.
Send a batch
The body is a JSON array of message objects (or { "Messages": [...] }), up to 500
per request. You get one result object per message, in order; an individual failure does not fail the rest of
the batch.
[
{ "To": "a@example.com", "SubmittedAt": "...", "MessageID": "...", "ErrorCode": 0, "Message": "OK" },
{ "To": "b@example.com", "ErrorCode": 300, "Message": "Provide either HtmlBody or TextBody." }
]Message log
Query parameters: count (max 500), offset, status, tag, recipient.
{
"TotalCount": 1,
"Messages": [
{
"MessageID": "f5ab446c-...",
"To": "customer@example.com",
"From": "hello@yourdomain.com",
"Subject": "Welcome aboard",
"Status": "sent",
"Tag": "welcome",
"MessageStream": "outbound",
"SubmittedAt": "2026-05-31T22:28:43+00:00"
}
]
}Single message
Returns the full message - bodies, headers, metadata and the chronological MessageEvents (delivery, open, click, bounce, spam).
Provider events
Your sending infrastructure reports the fate of an outbound message here. Type is one of delivery, bounce, spam_complaint.
{
"Type": "bounce",
"MessageID": "f5ab446c-...",
"Recipient": "customer@example.com",
"Details": { "Type": "HardBounce", "Description": "No such user" }
}Recording a hard bounce or spam complaint adds the recipient to the hive’s suppression list and fans the event out to your subscribed webhooks.