Event: `mailbox.status_changed`

Fires whenever a mailbox transitions to a new lifecycle status — from initial provisioning all the way through to cancellation.

🔗 For the shared HTTP contract, headers, signature verification, and retry logic, see the Webhook Integration & Signature Verification page.

🔴 Security — read this first

The mailbox payload contains decrypted mailbox credentials as plaintext:

password — main mailbox login password

app_password — application-specific password

secret — secret key for 2FA / secondary auth

These fields are transmitted because many customers need them to provision downstream sequencers. This is a deliberate product choice and it creates real security obligations on your side:

Use an HTTPS webhook endpoint. The mailbox payload is plaintext credentials — TLS is the only thing that protects them in transit. We strongly recommend never configuring a plain HTTP URL for an integration that receives mailbox events.

Treat your webhook endpoint as a secrets-handling endpoint. Restrict access, review who can read its logs, apply the same controls you'd apply to a password vault.

Never log these fields. Not in application logs, not in error tracking (Sentry, Datadog), not in nginx access logs.

Store them encrypted at rest on your side, with an encryption key that is rotated separately from your application code.

Clear plaintext from memory as soon as you've persisted the encrypted copy. Don't keep the decrypted values in long-lived objects.

Rotate immediately if leaked. Use the mailbox management API to push a new password if you suspect exposure.

OAuth refresh_token values are intentionally excluded from webhook payloads for security reasons. If you need them, use the authenticated mailbox read API instead.

Applies to

Scope	Value
Providers	All InboxKit-managed mailboxes. `data.mailbox.platform` is currently one of `GOOGLE`, `MICROSOFT`, `AZURE`, or `SMTP`.
Trigger	Any significant change to `mailbox.status`.
Typical cadence	Delivered to your endpoint within approximately 30 seconds of the status change.

Forward-compatibility tip. InboxKit may add new platform values in the future. When you switch on data.mailbox.platform, always include a default branch so an unknown platform logs a warning instead of crashing your handler.

Headers (reminder)

POST /your-path HTTP/1.1
Content-Type: application/json
User-Agent: InboxKit-Webhook/1.0
X-InboxKit-Event: mailbox.status_changed
X-InboxKit-Timestamp: 2024-01-10T16:45:30.456Z
X-InboxKit-Signature: sha256=<hex>

Payload envelope

{
  "event": "mailbox.status_changed",
  "timestamp": "<ISO 8601 UTC>",
  "team_id": "<your team uid>",
  "team_name": "<your team name>",
  "data": {
    "mailbox": { /* see fields below */ },
    "metadata": { /* see fields below */ }
  }
}

`data.mailbox` fields

Every field InboxKit sends in a mailbox.status_changed webhook is listed below.

Field	Type	Nullable	Description
`uid`	string	no	Unique, stable identifier for this mailbox. Use this as your idempotency key.
`email`	string	no	Full email address (computed as `${username}@${domain_name}`).
`username`	string	no	Local-part of the email address.
`first_name`	string	no (may be empty)	First name on the mailbox.
`last_name`	string	no (may be empty)	Last name on the mailbox.
`profile_picture`	string	no (may be empty)	URL to profile picture, or `""` if not set.
`status`	enum	no	New status. See the status reference table below.
`previous_status`	string \| null	yes	Previous status before this transition, if known.
`platform`	enum	no	`GOOGLE`, `MICROSOFT`, `AZURE`, or `SMTP`. New values may be added in the future.
`renewal_date`	ISO 8601 \| null	yes	When the mailbox subscription is next due for renewal.
`renewal_status`	enum	no	`na` \| `pending` \| `completed` \| `failed` \| `cancelled` \| `permanent_failure`.
`is_admin`	boolean	no	Whether this mailbox has admin privileges on its Workspace tenant.
`password`	string	no	🔴 DECRYPTED main mailbox password. See security section above.
`app_password`	string	no	🔴 DECRYPTED application-specific password (e.g. for SMTP sending).
`secret`	string	no	🔴 DECRYPTED secret key for 2FA or secondary auth.
`is_add_on`	boolean	no	Whether this is an add-on mailbox (piggy-backed on an existing Workspace).

Not included: refresh_token is intentionally omitted from the payload. If you need it, fetch it via the authenticated API.

`data.metadata` fields

Field	Type	Description
`updated_at`	ISO 8601	When the mailbox document was last updated in InboxKit's database.
`workspace_id`	string	Internal workspace identifier.
`domain_id`	string	Internal identifier of the domain the mailbox belongs to.
`domain_name`	string	The full domain name the mailbox belongs to (same as the part after `@` in `email`).

Status value reference

Every status listed below will trigger a mailbox.status_changed webhook when a mailbox transitions to it.

Pre-active lifecycle

Status	What it means
`pending`	Initial state — mailbox has been requested but provisioning hasn't started.
`processing`	Generic "work in progress" state.
`waiting_for_dns_propagation`	Mailbox is waiting on DNS records on its domain to propagate.
`waiting_for_activation_email`	Waiting for the provider's activation email (Microsoft).
`activation_email_received`	Activation email received; moving on to configuration.
`configuring_workspace`	Google/Microsoft workspace-level setup in progress.
`configuring_dns`	Applying mailbox-specific DNS records (MX/SPF/DKIM).
`configuring_dkim`	Generating and publishing DKIM keys.
`configuring_auth`	Final authentication setup (OAuth consent, app passwords, etc.).
`finalizing_setup`	Last-mile tasks before the mailbox goes active.

Active lifecycle

Status	What it means
`active`	Mailbox is live and ready to send/receive. Credentials in this payload are current.
`inactive`	Mailbox exists but is currently paused.
`scheduled`	Scheduled to become active at a future time.

Terminal / failure states

Status	What it means
`suspended`	Mailbox has been suspended (admin action or provider-side).
`failed`	Provisioning or a state transition failed. Check `previous_status` for context.
`renewal_failed`	The mailbox's subscription renewal (billing) failed. Typically appears alongside `renewal_status: "failed"`. Surface this to your billing flow so the customer can retry payment.
`scheduled_for_cancellation`	Customer cancelled; mailbox will be cancelled soon.
`cancelled`	Subscription cancelled.
`archived`	Mailbox has been archived but retained.
`deleted`	Fully removed from InboxKit. Terminal state.

Example receiver (Node.js)

Examples

Use the selector on the right-hand side to see different realistic transitions.

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

Authorization: Bearer ********************

Event: Mailbox Status Changed

Event: `mailbox.status_changed`

🔴 Security — read this first

Applies to

Headers (reminder)

Payload envelope

`data.mailbox` fields

`data.metadata` fields

Status value reference

Pre-active lifecycle

Active lifecycle

Terminal / failure states

Example receiver (Node.js)

Examples

Request

Responses

Event: Mailbox Status Changed

Event: mailbox.status_changed#

🔴 Security — read this first#

Applies to#

Headers (reminder)#

Payload envelope#

data.mailbox fields#

data.metadata fields#

Status value reference#

Pre-active lifecycle#

Active lifecycle#

Terminal / failure states#

Example receiver (Node.js)#

Examples#

Request

Responses

Event: `mailbox.status_changed`

🔴 Security — read this first

Applies to

Headers (reminder)

Payload envelope

`data.mailbox` fields

`data.metadata` fields

Status value reference

Pre-active lifecycle

Active lifecycle

Terminal / failure states

Example receiver (Node.js)

Examples