API Documentation

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

Parameters

Response

{
  "data": {
    "id": 1,
    "address": "ax7k2m@acme.mailbrew.dev",
    "webhook_url": null,
    "expires_at": "2026-03-29T13:00:00+00:00",
    "is_permanent": false,
    "created_at": "2026-03-29T12:00:00+00:00"
  }
}

List Addresses — Returns the addresses created with this API key and the addresses auto-created on receipt for the same company. Auto-created addresses can be read with any API key from the same company.

Response

{
  "data": [
    {
      "id": 1,
      "address": "ax7k2m@acme.mailbrew.dev",
      "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 Address — Get details of an address.

Response

{
  "data": {
    "id": 1,
    "address": "ax7k2m@acme.mailbrew.dev",
    "webhook_url": null,
    "expires_at": "2026-03-29T13:00:00+00:00",
    "is_permanent": false,
    "created_at": "2026-03-29T12:00:00+00:00"
  }
}

List Emails — List emails received at the specified address. Emails are deleted after the retention period (7 days on every plan; organizations can shorten it in Security settings).

Response

{
  "data": [
    {
      "id": 1,
      "from_address": "noreply@example.com",
      "subject": "Your verification code",
      "text_body": "Your code is: 847291",
      "received_at": "2026-03-29T12:05:00+00:00"
    }
  ]
}

Get Email — Get details of a specific email.

Response

{
  "data": {
    "id": 1,
    "from_address": "noreply@example.com",
    "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"
  }
}

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

Parameters

Response

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

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

Parameters

Response

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

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

Parameters

Response

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

Forward Email — Forward a received email only to an active, verified member of your company.

Parameters

Response

{
  "data": {
    "forwarded": true,
    "to": "dev@example.com"
  },
  "success": true
}

Delete Address — Delete an address.

Response

204 No Content

Wait for Emails — Wait for emails using long-polling.

Parameters

Response

{ "data": [] }

Verify Email Sequence — Verify that matching emails arrive in order.

Parameters

Response

{ "data": { "passed": true, "steps": [] } }

Compare Emails — Compare two emails.

Parameters

Response

{ "data": { "email_id": 1, "against_id": 2, "fields": {} } }

Analyze Deliverability — Analyze deliverability including SPF, DKIM, and DMARC.

Response

{ "data": { "score": 100, "checks": [], "recommendations": [] } }

List Captured Emails — List emails sent over SMTP AUTH to external recipients (e.g. gmail.com), looked up by envelope recipient (RCPT TO), including BCC. A MailBrew address cannot be used as to (use the address endpoints). Get one, extract OTP or links with /api/mailbrew/emails/{id}, /otp and /links.

Parameters

Response

{
  "data": [
    {
      "id": 1,
      "from_address": "noreply@example.com",
      "subject": "Your verification code",
      "text_body": "Your code is: 847291",
      "received_at": "2026-03-29T12:05:00+00:00"
    }
  ]
}

Wait for Captured Emails — Wait for captured emails using long-polling. Same parameters as waiting on an address.

Parameters

Response

{ "data": [] }

List Webhooks — List global webhooks.

Response

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

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

Parameters

Response

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

Update Webhook — Update a webhook URL, events, or active state.

Parameters

Response

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

Delete Webhook — Delete a webhook.

Response

204 No Content

const { MailBrew } = require('@mailbrew/sdk');
const client = new MailBrew('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"