API Documentation

Buzzz API Reference

Everything you need to send emails programmatically. Simple REST API, webhooks for events, and SDKs for popular languages.

API Status: OperationalREST APIJSONHTTPS Only

Quick Start

Send your first email in 30 seconds

Send a POST request to the emails endpoint

curl -X POST https://api.buzzz.email/api/v1/emails \
  -H "Authorization: Bearer bz_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "recipient@example.com",
    "subject": "Hello from Buzzz!",
    "html": "<h1>Welcome!</h1><p>Your first email via Buzzz API.</p>"
  }'

Get Your API Key

Authentication

All API requests require authentication via API key in the Authorization header:

Authorization: Bearer bz_your_api_key_here

Security Best Practices

Never expose API keys in client-side code
Use environment variables to store keys
Rotate keys periodically
Use separate keys for production and development

Send Email

POST/api/v1/emails

Send an email to one or more recipients

Request Body

Field	Type	Required	Description
to	string	Required	Recipient email address
subject	string	Required	Email subject line
html	string	html or text	HTML body content
text	string	html or text	Plain text body content
from	string	Optional	Sender email (must be verified)
fromName	string	Optional	Sender display name
replyTo	string	Optional	Reply-to address
cc	string	Optional	CC recipients (comma-separated)
bcc	string	Optional	BCC recipients (comma-separated)
category	string	Optional	transactional (default) or marketing. See below.

Transactional vs. marketing

This endpoint defaults to transactional: one-to-one mail the recipient is expecting — receipts, password resets, alerts. Transactional mail carries no unsubscribe headers or footer, and is still delivered to addresses that unsubscribed from your marketing lists (though never to addresses that bounced or filed a spam complaint).

Promotional mail must be sent with "category": "marketing". Marketing sends automatically get RFC 8058 List-Unsubscribe and List-Unsubscribe-Post headers plus an unsubscribe footer, and are rejected for recipients who have unsubscribed. The unsubscribe link identifies the to address, so send marketing mail to one recipient per request.

Sending promotional content as transactional is a Terms of Service violation: it puts the shared sending reputation at risk and denies recipients the opt-out the law requires.

Suppression

Every address in to, cc and bcc is checked against your suppression list. If any one of them has hard-bounced, complained, or (for marketing sends) unsubscribed, the whole request is rejected with 422 recipient_suppressed and nothing is sent.

Example Request

curl -X POST https://api.buzzz.email/api/v1/emails \
  -H "Authorization: Bearer bz_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "customer@example.com",
    "subject": "Your Order Confirmation",
    "from": "orders@yourdomain.com",
    "fromName": "Your Store",
    "replyTo": "support@yourdomain.com",
    "html": "<h1>Order Confirmed!</h1><p>Your order #12345 is confirmed.</p>"
  }'

Response

{
  "id": "email_abc123xyz",
  "status": "SENT",
  "message": "Email sent successfully"
}

List Emails

GET/api/v1/emails

Retrieve a paginated list of emails sent via your API key

Query Parameters

Parameter	Type	Default	Description
page	number	1	Page number
limit	number	50	Items per page (max 100)
status	string	-	Filter: PENDING, SENT, FAILED, BOUNCED

Example Request

curl "https://api.buzzz.email/api/v1/emails?page=1&limit=10&status=SENT" \
  -H "Authorization: Bearer bz_your_api_key"

Response

{
  "emails": [
    {
      "id": "email_abc123",
      "fromEmail": "you@yourdomain.com",
      "fromName": "Your Company",
      "toEmail": "customer@example.com",
      "subject": "Order Confirmation",
      "status": "SENT",
      "createdAt": "2025-12-19T10:30:00.000Z",
      "sentAt": "2025-12-19T10:30:01.000Z",
      "errorMsg": null
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 156,
    "totalPages": 16
  }
}

Send SMS

POST/api/v1/sms

Send a single SMS message to one recipient

Request Body

Field	Type	Required	Description
to	string	Required	Recipient phone number. Stored in E.164; a number that cannot be resolved to E.164 is rejected as a bad request.
body	string	Required	Message text (max 1600 characters)
senderId	string	Optional	Alphanumeric sender ID (max 20 characters), where your provider allows one
category	string	Optional	marketing (default) or transactional. See below.

Transactional vs. marketing

Unlike the email endpoint, this one defaults to marketing: the stricter setting. A marketing SMS is never delivered to a number that replied STOP, nor to one the carrier has blocked. If you never send the field, nothing about your integration changes.

Send one-time passcodes, alerts and other messages the recipient is expecting with "category": "transactional". Transactional narrows which opt-outs apply — it does not turn opt-out enforcement off. A voluntary STOP no longer blocks the send, because withdrawing consent to promotions is not a request to be locked out of your own account. A carrier-level block still refuses it: the carrier will not deliver the message whatever you label it.

Transactional sends require the transactional_sms entitlement on your account. Without it the request is refused rather than quietly downgraded, so a misconfigured integration fails loudly instead of dropping passcodes. Labelling promotional content as transactional is a Terms of Service violation and, for SMS to numbers that opted out, a legal exposure under the TCPA.

Opt-outs

Replies of STOP, UNSUBSCRIBE and the other carrier-standard keywords are recorded against your account, and START re-enables the number. A send that the opt-out list refuses returns 422 recipient_opted_out — the message names the reason, which differs by category — and is not counted against your monthly allowance.

Example Request

curl -X POST https://api.buzzz.email/api/v1/sms \
  -H "Authorization: Bearer bz_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+27821234567",
    "body": "Your verification code is 481920.",
    "category": "transactional"
  }'

Response

{
  "id": "sms_abc123xyz",
  "status": "SENT",
  "segments": 1,
  "message": "SMS sent successfully"
}

Webhooks

Delivery events are tracked automatically for every email you send. Buzzz receives delivery receipts, bounces, and complaints from the sending infrastructure and updates your email and contact statuses in real time — no setup required on your side.

Supported Events

Event	Description	Action Taken
delivered	Email successfully delivered	Email status → SENT
bounce	Email bounced (hard or soft)	Contact status → BOUNCED
complaint	Recipient marked as spam	Contact status → COMPLAINED
open	Email was opened	Campaign opens +1
click	Link was clicked	Campaign clicks +1
unsubscribe	Recipient unsubscribed	Contact status → UNSUBSCRIBED

Automatic Contact Management

When a bounce or complaint webhook is received, Buzzz automatically updates the contact's status and excludes them from future sends. This protects your sender reputation.

SDKs & Code Examples

// Using fetch (Node.js 18+)
const response = await fetch('https://api.buzzz.email/api/v1/emails', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.BUZZZ_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    to: 'user@example.com',
    subject: 'Hello from Node.js!',
    html: '<h1>Hello!</h1><p>Sent via Buzzz API</p>',
  }),
});

const data = await response.json();
console.log(data.id); // email_abc123

Error Codes

Status	Error	Description
400	Bad Request	Missing required fields or invalid data format
401	Unauthorized	Missing or invalid API key
403	Forbidden	API key lacks required permissions
404	Not Found	Resource doesn't exist
429	Too Many Requests	Rate limit exceeded. Wait and retry.
500	Internal Error	Server error. Please retry or contact support.

Error Response Format

{
  "error": "Bad Request",
  "message": "Missing required field: to",
  "statusCode": 400
}

Ready to start sending?

Create your free account and get your API key in seconds.

Get Started Free Full API Reference