Mailboxes

Configure mailbox policy

Updates outbound footer policy and/or first-contact inbound policy for an owned mailbox. Inbound policy changes are independent from footer-policy changes and take effect on the next inbound Lambda invocation.

patch/mailboxes/v1/{mailbox_id}

Request

  • Base URL: https://api.run402.com
  • URL: https://api.run402.com/mailboxes/v1/{mailbox_id}
  • Auth: HTTP bearer

Path parameters

mailbox_idstring uuid required

Mailbox ID

Request body

footer_policy'run402_transparency' | 'none'

Configured outbound footer policy for this mailbox.

inbound_policy'reply_only' | 'allowlist' | 'open'

First-contact inbound policy. reply_only is the default and preserves the sent-history gate.

inbound_allowliststring[]

Case-insensitive allowlist entries for inbound_policy=allowlist. Supports exact addresses and *@domain wildcards.

Response

Mailbox footer policy updated

mailbox_idstring
addressstring

Current effective primary sender/recipient address. Uses ProjectDomain effective custom mailbox state only; otherwise uses the managed project mail host.

managed_addressstring

Stable Run402-managed address for this mailbox. Remains receive-compatible permanently, including after custom-domain activation.

slugstring

Project-scoped email local part.

project_idstring

Run402 project ID. Public IDs are not UUIDs.

status'active' | 'suspended' | 'tombstoned' | 'deleted'
footer_policy'run402_transparency' | 'none'

Configured outbound footer policy for this mailbox. Defaults to run402_transparency.

effective_footer_policy'run402_transparency' | 'none'

Footer policy that will be applied to sends after tier gating. Prototype-tier projects are always run402_transparency.

footer_policy_locked_reason'prototype_tier' nullable

Null when configurable; prototype_tier when the project tier forces the Run402 transparency footer.

is_default_outboundboolean

True when this mailbox is the project's default sender for implicit app/helper email sends.

is_auth_senderboolean

True when this mailbox is the configured sender for auth magic-link and invite emails.

can_sendboolean

True when the mailbox is active and can currently send outbound email.

send_blocked_reasonstring nullable

Machine-readable reason when can_send is false, such as mailbox_suspended or mailbox_deleted.

domain_kind'managed' | 'custom'

Whether the primary address currently uses the Run402-managed project mail host or ProjectDomain effective custom mailbox state.

address_domainstring

Domain portion of the current primary address.

managed_domainstring

Stable Run402-managed project mail domain.

custom_domain_readyboolean

True when ProjectDomain effective state has custom mailbox addresses active.

can_receiveboolean

True when the mailbox has an inbound route for its current address namespace.

sends_todayinteger
unique_recipientsinteger
created_atstring date-time
updated_atstring date-time
inbound_policy'reply_only' | 'allowlist' | 'open'

First-contact inbound policy. reply_only is the default and preserves the sent-history gate.

inbound_allowliststring[]

Case-insensitive allowlist entries for inbound_policy=allowlist. Supports exact addresses and *@domain wildcards.

suspended_reasonstring nullable
suspended_atstring date-time nullable
suspended_evidenceobject nullable

Example response

{
  "mailbox_id": "mbx_1780076428285_dlnfqq",
  "address": "notifications@kysigned3.mail.run402.com",
  "managed_address": "notifications@kysigned3.mail.run402.com",
  "project_id": "prj_1741340000_0042",
  "address_domain": "kysigned3.mail.run402.com",
  "managed_domain": "kysigned3.mail.run402.com",
  "next_action": {
    "method": "POST",
    "path": "/tiers/v1/hobby",
    "auth": "x402"
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.