Mailbox API · Beta

List mailbox events

GET

/events

const url = 'https://api.builders.ac/api/mailbox/v1beta1/events?type=message.received&classification=reply%2Cother_inbound&limit=20&order=created_at.desc';
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request GET \
  --url 'https://api.builders.ac/api/mailbox/v1beta1/events?type=message.received&classification=reply%2Cother_inbound&limit=20&order=created_at.desc' \
  --header 'Authorization: Bearer <token>'

The messages observed on your mailboxes over the last 7 days, newest first unless order=created_at.asc. Paged by cursor over (created_at, id): pass next_cursor as starting_after, with the same filters and order.

See Events in the introduction for coverage, latency and how to follow the feed without missing late-classified events.

Authorizations

BearerAuth

Parameters

Query Parameters

type

string

Event types to include. One value, or several separated by commas. Omitted, it does not narrow.

Examples

received

message.received

classification

string

Classifications to include: outreach, warmup, reply, warmup_reply, autoresponder, other_inbound. One value, or several separated by commas. Omitted, it does not narrow.

Examples

replies

reply,other_inbound

domain_id

string

dom_ ids of domains you own. One value, or several separated by commas. Omitted, it does not narrow. An id that is unknown or not yours answers 404.

created[gte]

string format: date-time

Only events whose message was received at or after this time.

created[lte]

string format: date-time

Only events whose message was received at or before this time.

limit

integer

default: 20 >= 1 <= 100

starting_after

string

The next_cursor of the previous page.

order

string

default: created_at.desc

Allowed values: created_at.desc created_at.asc

Responses

200

A page of events.

application/json

Event list

object

data

required

Array<object>

Event

One message observed on one of your mailboxes. Unknown values are null, never omitted.

object

required

string

/^evt_[0-7][0-9a-hjkmnp-tv-z]{25}$/

object

required

Allowed value: event

type

required

message.sent when the message was sent from your mailbox, message.received when it arrived in it.

string

Allowed values: message.sent message.received

classification

required

What the message was classified as, best-effort. A reply to your outreach is message.received + reply. other_inbound is inbound mail with no reply evidence — it can still be a prospect writing a fresh email or answering from another address.

string

Allowed values: outreach warmup reply warmup_reply autoresponder other_inbound

mailbox

required

Your mailbox, as its full address in lower case. Usable as {email} on /azure.

string format: email

counterparty

required

The recipient of a sent message (the first one with an address), the sender of a received one.

string | null

subject

required

string | null

message_id

required

Microsoft Graph’s id for this event’s own copy of the message — the Sent Items and Inbox copies have different ids. Fetch it with GET /azure/v1.0/users/{mailbox}/messages/{message_id}. Graph ids change when a message moves folder; if it has, find the message with GET /azure/v1.0/users/{mailbox}/messages?$filter=internetMessageId eq '…'.

string | null

internet_message_id

required

The RFC 5322 Message-ID header. Use it as In-Reply-To to answer in the same thread.

string | null

domain_id

required

The mailbox’s domain, as the Provisioning API’s dom_ id.

string | null

/^dom_[0-7][0-9a-hjkmnp-tv-z]{25}$/

created_at

required

When the mailbox received the message. Second precision.

string format: date-time

has_more

required

false on the last page of the retained window.

boolean

next_cursor

required

Pass as starting_after, with the same filters and order, for the next page. null on the last page.

string | null

Example

{
  "data": [
    {
      "id": "evt_01k5bz9wqzf1tvbsm7j3a2e6hd",
      "object": "event",
      "type": "message.received",
      "classification": "reply",
      "mailbox": "sender@yourdomain.com",
      "counterparty": "lead@prospect.com",
      "subject": "Re: Quick question",
      "message_id": "AAMkAGI2TG93AAA=",
      "internet_message_id": "<CAF4x9Q@mail.prospect.com>",
      "domain_id": "dom_01k4q7m2c8e5r9t3v6w1y0z2ab",
      "created_at": "2026-09-15T08:24:57+00:00"
    }
  ],
  "has_more": true,
  "next_cursor": "eyJjcmVhdGVkX2F0IjoiMjAyNi0wOS0xNSAwODoyNDo1Ny4wMDAwMDArMDA6MDAifQ.c2lnbmF0dXJl"
}

401

No API key (authentication_required), or one that is unknown or revoked (invalid_api_key). Carries WWW-Authenticate: Bearer.

application/problem+json

Problem

An RFC 9457 problem. Branch on code.

object

type

required

The catalogue entry for code, under /problems.

string format: uri

title

required

string

status

required

integer

detail

required

string

code

required

string

retryable

required

boolean

correlation_id

required

Quote this in support requests. Also sent as x-correlation-id.

string

retry_after

Present on 429: when to retry.

string format: date-time

errors

Per parameter, what is wrong with it.

object

key

additional properties

Array<string>

Example

{
  "type": "https://api.builders.ac/api/mailbox/v1beta1/problems/invalid_api_key",
  "title": "Invalid API key",
  "status": 401,
  "detail": "The supplied Mailbox API key is invalid or revoked.",
  "code": "invalid_api_key",
  "retryable": false,
  "correlation_id": "a26397a7-04e1-4c8f-9b1d-2f7e3c5a8d10"
}

Headers

WWW-Authenticate

string

Allowed value: Bearer

403

The credential is valid, but its Core customer account is inactive (account_inactive).

application/problem+json

Problem

An RFC 9457 problem. Branch on code.

object

type

required

The catalogue entry for code, under /problems.

string format: uri

title

required

string

status

required

integer

detail

required

string

code

required

string

retryable

required

boolean

correlation_id

required

Quote this in support requests. Also sent as x-correlation-id.

string

retry_after

Present on 429: when to retry.

string format: date-time

errors

Per parameter, what is wrong with it.

object

key

additional properties

Array<string>

Example

{
  "type": "https://api.builders.ac/api/mailbox/v1beta1/problems/account_inactive",
  "title": "Account inactive",
  "status": 403,
  "detail": "This account is inactive.",
  "code": "account_inactive",
  "retryable": false,
  "correlation_id": "a26397a7-04e1-4c8f-9b1d-2f7e3c5a8d10"
}

404

A domain_id that is unknown or not yours. errors.domain_id names it.

application/problem+json

Problem

An RFC 9457 problem. Branch on code.

object

type

required

The catalogue entry for code, under /problems.

string format: uri

title

required

string

status

required

integer

detail

required

string

code

required

string

retryable

required

boolean

correlation_id

required

Quote this in support requests. Also sent as x-correlation-id.

string

retry_after

Present on 429: when to retry.

string format: date-time

errors

Per parameter, what is wrong with it.

object

key

additional properties

Array<string>

Example

{
  "type": "https://api.builders.ac/api/mailbox/v1beta1/problems/not_found",
  "title": "Not found",
  "status": 404,
  "detail": "The requested resource was not found.",
  "code": "not_found",
  "retryable": false,
  "correlation_id": "a26397a7-04e1-4c8f-9b1d-2f7e3c5a8d10",
  "errors": {
    "domain_id": [
      "The domain \"dom_01k4q7m2c8e5r9t3v6w1y0z2ab\" was not found or is not accessible."
    ]
  }
}

410

With order=created_at.asc, a starting_after older than the retention window. Restart with created[gte].

application/problem+json

Problem

An RFC 9457 problem. Branch on code.

object

type

required

The catalogue entry for code, under /problems.

string format: uri

title

required

string

status

required

integer

detail

required

string

code

required

string

retryable

required

boolean

correlation_id

required

Quote this in support requests. Also sent as x-correlation-id.

string

retry_after

Present on 429: when to retry.

string format: date-time

errors

Per parameter, what is wrong with it.

object

key

additional properties

Array<string>

Example

{
  "type": "https://api.builders.ac/api/mailbox/v1beta1/problems/cursor_expired",
  "title": "Cursor expired",
  "status": 410,
  "detail": "This cursor points before the retention window, so continuing would skip events that are no longer kept. Restart the listing with created[gte].",
  "code": "cursor_expired",
  "retryable": false,
  "correlation_id": "a26397a7-04e1-4c8f-9b1d-2f7e3c5a8d10"
}

422

An invalid parameter, or a cursor reused with different filters or order. errors names each offending parameter.

application/problem+json

Problem

An RFC 9457 problem. Branch on code.

object

type

required

The catalogue entry for code, under /problems.

string format: uri

title

required

string

status

required

integer

detail

required

string

code

required

string

retryable

required

boolean

correlation_id

required

Quote this in support requests. Also sent as x-correlation-id.

string

retry_after

Present on 429: when to retry.

string format: date-time

errors

Per parameter, what is wrong with it.

object

key

additional properties

Array<string>

Example

{
  "type": "https://api.builders.ac/api/mailbox/v1beta1/problems/validation_error",
  "title": "Validation failed",
  "status": 422,
  "detail": "One or more request fields are invalid.",
  "code": "validation_error",
  "retryable": false,
  "correlation_id": "a26397a7-04e1-4c8f-9b1d-2f7e3c5a8d10",
  "errors": {
    "type": [
      "\"message.opened\" is not an event type. Use message.sent or message.received."
    ]
  }
}

429

Rate limit exceeded — 60 requests per minute per credential and per account, shared with the Graph surface.

application/problem+json

Problem

An RFC 9457 problem. Branch on code.

object

type

required

The catalogue entry for code, under /problems.

string format: uri

title

required

string

status

required

integer

detail

required

string

code

required

string

retryable

required

boolean

correlation_id

required

Quote this in support requests. Also sent as x-correlation-id.

string

retry_after

Present on 429: when to retry.

string format: date-time

errors

Per parameter, what is wrong with it.

object

key

additional properties

Array<string>

Example

{
  "type": "https://api.builders.ac/api/mailbox/v1beta1/problems/rate_limit_exceeded",
  "title": "Rate limit exceeded",
  "status": 429,
  "detail": "Too many requests were made for this policy.",
  "code": "rate_limit_exceeded",
  "retryable": true,
  "correlation_id": "a26397a7-04e1-4c8f-9b1d-2f7e3c5a8d10",
  "retry_after": "2026-09-15T08:25:31+00:00"
}

Headers

Retry-After

integer

Seconds to wait before retrying.

X-RateLimit-Limit

integer

X-RateLimit-Remaining

integer

X-RateLimit-Reset

integer

Unix timestamp at which the window resets.

503

Temporarily unavailable. Retry later.

application/problem+json

Problem

An RFC 9457 problem. Branch on code.

object

type

required

The catalogue entry for code, under /problems.

string format: uri

title

required

string

status

required

integer

detail

required

string

code

required

string

retryable

required

boolean

correlation_id

required

Quote this in support requests. Also sent as x-correlation-id.

string

retry_after

Present on 429: when to retry.

string format: date-time

errors

Per parameter, what is wrong with it.

object

key

additional properties

Array<string>

Example

{
  "type": "https://api.builders.ac/api/mailbox/v1beta1/problems/service_unavailable",
  "title": "Service unavailable",
  "status": 503,
  "detail": "Retry the request later; the service is temporarily unavailable.",
  "code": "service_unavailable",
  "retryable": true,
  "correlation_id": "a26397a7-04e1-4c8f-9b1d-2f7e3c5a8d10"
}