API Documentation

MailBrew REST API Reference

Getting Started

MailBrew can be used in two ways.

SMTP

SMTP Mode (Email Send Testing)

Point your app's SMTP to MailBrew (smtp.mailbrew.dev). View sent emails in your dashboard's shared inbox in real time.

SMTP Config →

Cloud API

Cloud API Mode (E2E & CI Testing)

Create test email addresses via API, receive real emails, and automate OTP extraction, link verification, and email assertions. CI/CD ready.

Cloud API →

SMTP Configuration

Set the following environment variables in your application.

Use SMTP credentials generated in the Dashboard "SMTP Settings" page. All emails sent with these credentials are automatically routed to your company's shared inbox, regardless of the recipient address. No need to worry about recipient addresses during testing.

Laravel (.env)

MAIL_MAILER=smtp
MAIL_HOST=smtp.mailbrew.dev
MAIL_PORT=1025
MAIL_USERNAME=mb_smtp_xxxxx
MAIL_PASSWORD=your_smtp_password
MAIL_ENCRYPTION=null

For Node.js (Nodemailer):

const transporter = nodemailer.createTransport({
  host: 'smtp.mailbrew.dev',
  port: 1025,
  secure: false,
  auth: {
    user: 'mb_smtp_xxxxx',
    pass: 'your_smtp_password',
  },
});

Web UI

Emails sent to MailBrew can be viewed in real-time via the Web UI. Supports HTML preview, attachment downloads, and full-text search.

https://mailbrew.dev

Cloud API

The following are MailBrew cloud service API endpoints. Authentication with an API key is required.

SDKs

Use our official SDKs for easy API integration.

npm install @brewmail/sdk

const { BrewMail } = require('@brewmail/sdk');
const client = new BrewMail('mb_your_key_here');

Methods

Address Management

createAddress(options?)

Create a temporary email address

const addr = await client.createAddress({ ttl: 3600 });
console.log(addr.address); // "[email protected]"

listAddresses()

List all addresses

const addresses = await client.listAddresses();

deleteAddress(address)

Delete an address

await client.deleteAddress('[email protected]');

Email Operations

waitForEmail(address, options?)

Wait for email via long-polling

const email = await client.waitForEmail(addr.address, { timeout: 30 });

listEmails(address)

List emails for an address

const emails = await client.listEmails(addr.address);

getEmail(address, emailId)

Get email details

const detail = await client.getEmail(addr.address, email.id);

Data Extraction

extractOtp(address, emailId, options?)

Extract OTP/verification code from email

const code = await client.extractOtp(addr.address, email.id);
// Custom pattern: { pattern: '\\d{4}' }

extractLinks(address, emailId, options?)

Extract links from email

const links = await client.extractLinks(addr.address, email.id);
// Filter: { pattern: 'verify' }

assertEmail(address, emailId, assertions)

Assert email properties (subject, from, body, etc.)

const result = await client.assertEmail(addr.address, email.id, {
  subject_contains: 'Welcome',
  body_contains: 'verify',
});
console.log(result.passed); // true

Convenience

captureOtp(options?)

Create address + wait + extract OTP in one call

const { address, waitAndExtract } = await client.captureOtp({ ttl: 120 });
// ... trigger email ...
const { code, email } = await waitAndExtract();

forwardEmail(address, emailId, to)

Forward email to another address

await client.forwardEmail(addr.address, email.id, '[email protected]');

Webhooks

createWebhook(url, options?)

Create a global webhook

const wh = await client.createWebhook('https://example.com/hook', {
  events: ['email.received'],
});

listWebhooks()

List webhooks

const webhooks = await client.listWebhooks();

deleteWebhook(id)

Delete a webhook

await client.deleteWebhook(wh.id);

Authentication

All API requests require an API key. Include it in the X-API-Key header.

X-API-Key: mb_your_key_here

Scopes

If an API key has scopes assigned, requests without the required scope will return a 403 error. Keys without scopes have full access.

addresses:read— List and view addresses

addresses:write— Create addresses

addresses:delete— Delete addresses

emails:read— List, view emails, extract OTP and links

Address Format

Generated addresses use your company subdomain. If a custom domain is configured, it will be used instead.

{random}@{company-slug}.mailbrew.dev

Base URL

https://mailbrew.dev/api/mailbrew

Endpoints

POST

/api/mailbrew/addresses

addresses:write

Create Address — Generate an email address. Set ttl=0 to create a permanent (non-expiring) address.

Parameters

ttlinteger

optional

Time to live in seconds. Default 3600. Set 0 for permanent

webhook_urlstring

optional

Notification URL on email receipt (per-address)

local_partstring

optional

Custom local part

Response

{
  "data": {
    "id": 1,
    "address": "[email protected]",
    "webhook_url": null,
    "expires_at": "2026-03-29T13:00:00+00:00",
    "is_permanent": false,
    "created_at": "2026-03-29T12:00:00+00:00"
  }
}

GET

/api/mailbrew/addresses

addresses:read

List Addresses — List addresses created with your API key.

Response

{
  "data": [
    {
      "id": 1,
      "address": "[email protected]",
      "webhook_url": null,
      "expires_at": "2026-03-29T13:00:00+00:00",
      "is_permanent": false,
      "created_at": "2026-03-29T12:00:00+00:00"
    }
  ]
}

GET

/api/mailbrew/addresses/{address}

addresses:read

Get Address — Get details of an address.

Response

{
  "data": {
    "id": 1,
    "address": "[email protected]",
    "webhook_url": null,
    "expires_at": "2026-03-29T13:00:00+00:00",
    "is_permanent": false,
    "created_at": "2026-03-29T12:00:00+00:00"
  }
}

GET

/api/mailbrew/addresses/{address}/emails

emails:read

List Emails — List emails received at the specified address.

Response

{
  "data": [
    {
      "id": 1,
      "from_address": "[email protected]",
      "subject": "Your verification code",
      "text_body": "Your code is: 847291",
      "received_at": "2026-03-29T12:05:00+00:00"
    }
  ]
}

GET

/api/mailbrew/addresses/{address}/emails/{id}

emails:read

Get Email — Get details of a specific email.

Response

{
  "data": {
    "id": 1,
    "from_address": "[email protected]",
    "subject": "Your verification code",
    "text_body": "Your code is: 847291",
    "html_body": "<p>Your code is: <b>847291</b></p>",
    "received_at": "2026-03-29T12:05:00+00:00"
  }
}

GET

/api/mailbrew/addresses/{address}/emails/{id}/otp

emails:read

Extract OTP — Auto-extract OTP/verification codes from email body. Perfect for E2E tests.

Parameters

patternstring

optional

Custom regex pattern

Response

{
  "data": {
    "code": "847291",
    "email_id": 1,
    "source": "text_body"
  }
}

GET

/api/mailbrew/addresses/{address}/emails/{id}/links

emails:read

Extract Links — Auto-extract links (URLs) from email body. Perfect for invitation links and password reset flows.

Parameters

patternstring

optional

Regex pattern to filter links by domain

Response

{
  "data": {
    "links": [
      "https://example.com/verify?token=abc123",
      "https://example.com/unsubscribe"
    ],
    "email_id": 1,
    "source": "text_body"
  }
}

POST

/api/mailbrew/addresses/{address}/emails/{id}/assert

emails:read

Assert Email — Validate email content. Check subject, sender, recipient, and body content simultaneously.

Parameters

subjectstring

optional

Exact subject match

subject_containsstring

optional

Subject contains

fromstring

optional

Exact from address match

tostring

optional

To addresses contains

body_containsstring

optional

Body contains

Response

{
  "data": {
    "passed": true,
    "email_id": 1,
    "results": [
      { "field": "subject", "passed": true, "expected": "Welcome", "actual": "Welcome" },
      { "field": "body_contains", "passed": true, "expected": "verify" }
    ]
  }
}

POST

/api/mailbrew/addresses/{address}/emails/{id}/forward

emails:read

Forward Email — Forward a received email to another address.

Parameters

tostring

required

Destination email address

Response

{ "success": true }

DELETE

/api/mailbrew/addresses/{address}

addresses:delete

Delete Address — Delete an address.

Response

204 No Content

GET

/api/mailbrew/webhooks

List Webhooks — List global webhooks.

Response

{
  "data": [
    {
      "id": 1,
      "url": "https://example.com/hook",
      "events": ["email.received"],
      "is_active": true
    }
  ]
}

POST

/api/mailbrew/webhooks

Create Webhook — Register a global webhook. Notifies for all addresses.

Parameters

urlstring

required

Webhook URL

eventsarray

optional

Event array. Empty for all events

Response

{
  "data": {
    "id": 1,
    "url": "https://example.com/hook",
    "secret": "abc123...",
    "events": ["email.received"],
    "is_active": true
  }
}

Code Examples

const { BrewMail } = require('@brewmail/sdk');
const client = new BrewMail('mb_your_key_here');

// E2E test: create address, wait for email, extract OTP
const { address, waitAndExtract } = await client.captureOtp({ ttl: 120 });

// ... trigger email send to `address` ...

const { code, email } = await waitAndExtract();
console.log(code); // "847291"