Mailboxes

Create a mailbox

Creates a project-scoped mailbox local part. Without ProjectDomain effective custom mailbox addresses, the managed address is <slug>@<project-mail-host>.mail.run402.com. When ProjectDomain marks a custom mailbox address effective, the primary address is <slug>@<custom-domain> and managed_address remains a receive-compatible fallback. Reusing the same slug on another project is allowed; same-project active/suspended duplicates still return 409. Up to 5 mailboxes per project (flat across all tiers).

post/mailboxes/v1

Request

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

Request body

slugstring required

Mailbox local part, project-scoped (e.g. 'notifications' for notifications@<project-mail-host>.mail.run402.com)

Response

Mailbox created

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"
  },
  "next_actions": [
    {
      "method": "POST",
      "path": "/tiers/v1/hobby",
      "auth": "x402"
    }
  ]
}

Changes

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