API Reference

Base URL

All API requests are made to:

https://api.mailbreeze.com/api/v1

Authentication

Include your API key in the Authorization header with a Bearer prefix:

curl https://api.mailbreeze.com/api/v1/emails \
  -H "Authorization: Bearer sk_live_xxx"

Get your API key from the MailBreeze Dashboard.

Request Format

All requests should include:

Header	Value
`Content-Type`	`application/json`
`Authorization`	`Bearer <your-api-key>`

Request bodies must be valid JSON:

{
  "from": "hello@yourdomain.com",
  "to": "user@example.com",
  "subject": "Hello!",
  "html": "<p>Welcome!</p>"
}

Response Format

All responses are JSON wrapped in a standard envelope:

{
  "success": true,
  "data": { ... },
  "meta": {
    "timestamp": "2024-01-15T10:30:00.000Z",
    "requestId": "req_abc123",
    "path": "/api/v1/emails"
  }
}

Successful Response

Single resource:

{
  "success": true,
  "data": {
    "stats": {
      "total": 10000,
      "sent": 9850,
      "failed": 150
    }
  },
  "meta": { "timestamp": "...", "requestId": "...", "path": "..." }
}

Send email response:

{
  "success": true,
  "data": {
    "messageId": "abc123@mailbreeze.com",
    "skipped": false
  },
  "meta": { "timestamp": "...", "requestId": "...", "path": "..." }
}

List Response

Paginated lists include a pagination object within data:

{
  "success": true,
  "data": {
    "emails": [
      { "id": "msg_abc123", "subject": "Hello" },
      { "id": "msg_def456", "subject": "Welcome" }
    ],
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 150,
      "totalPages": 123
    }
  },
  "meta": { "timestamp": "...", "requestId": "...", "path": "..." }
}

Error Response

Errors also follow the envelope pattern:

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid email address format",
    "details": {
      "field": "to",
      "value": "invalid-email"
    }
  },
  "meta": { "timestamp": "...", "requestId": "..." }
}

SDKs automatically extract the data field, so you access response data directly without the wrapper.

HTTP Methods

Method	Usage
`GET`	Retrieve resources
`POST`	Create resources
`PUT`	Update resources
`DELETE`	Remove resources

Pagination

List endpoints support pagination:

Parameter	Type	Default	Description
`page`	integer	1	Page number
`limit`	integer	20	Items per page (max 100)

Example:

curl "https://api.mailbreeze.com/api/v1/emails?page=2&limit=50" \
  -H "Authorization: Bearer sk_live_xxx"

Timestamps

All timestamps are ISO 8601 format in UTC:

2024-01-15T10:30:00.000Z

IDs

Resources use prefixed IDs for easy identification:

Prefix	Resource
`msg_`	Email message
`lst_`	Contact list
`cnt_`	Contact
`att_`	Attachment
`ver_`	Verification

Test Mode

Use test API keys (sk_test_*) to simulate requests without sending real emails or using credits:

const mailbreeze = new MailBreeze({ apiKey: "sk_test_xxx" });

const result = await mailbreeze.emails.send({ ... });
console.log(result.sandbox); // true - email was simulated

SDKs

Official SDKs are available for popular languages:

JavaScript

npm install mailbreeze

Python

pip install mailbreeze

Go

go get github.com/MailBreeze/mailbreeze-go

PHP

composer require mailbreeze/mailbreeze-php

Rust

cargo add mailbreeze

Overview

Emails

Attachments

Lists

Contacts

Verification

Base URL

Authentication

Request Format

Response Format

Successful Response

List Response

Error Response

HTTP Methods

Timestamps

IDs

Test Mode

SDKs

JavaScript

Python

Go

PHP

Rust

​Base URL

​Authentication

​Request Format

​Response Format

​Successful Response

​List Response

​Error Response

​HTTP Methods

​Pagination

​Timestamps

​IDs

​Test Mode

​SDKs

JavaScript

Python

Go

PHP

Rust

Base URL

Authentication

Request Format

Response Format

Successful Response

List Response

Error Response

HTTP Methods

Pagination

Timestamps

IDs

Test Mode

SDKs