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)

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
  }
}

Webhooks

Webhooks notify your application in real-time when email events occur. Configure webhook URLs in your email provider settings.

SendGrid Webhook

/api/webhooks/sendgrid

Configure in SendGrid Dashboard → Settings → Mail Settings → Event Webhook

AWS SES Webhook

/api/webhooks/ses

Configure via SNS subscription to your SES configuration set

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