--- title: "Create a mailbox" method: POST path: "/mailboxes/v1" tags: ["Mailboxes"] --- # Create a mailbox `POST /mailboxes/v1` ## Request - Base URL: `https://api.run402.com` - URL: `https://api.run402.com/mailboxes/v1` - Auth: HTTP bearer Creates a project-scoped mailbox local part. Without ProjectDomain effective custom mailbox addresses, the managed address is @.mail.run402.com. When ProjectDomain marks a custom mailbox address effective, the primary address is @ 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). ## Request body - object - `slug` string, required: Mailbox local part, project-scoped (e.g. 'notifications' for notifications@.mail.run402.com) ## Response `201` Mailbox created - MailboxCreateResponse - `mailbox_id` string - `address` string: Current effective primary sender/recipient address. Uses ProjectDomain effective custom mailbox state only; otherwise uses the managed project mail host. - `managed_address` string: Stable Run402-managed address for this mailbox. Remains receive-compatible permanently, including after custom-domain activation. - `slug` string: Project-scoped email local part. - `project_id` string: 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_outbound` boolean: True when this mailbox is the project's default sender for implicit app/helper email sends. - `is_auth_sender` boolean: True when this mailbox is the configured sender for auth magic-link and invite emails. - `can_send` boolean: True when the mailbox is active and can currently send outbound email. - `send_blocked_reason` string, 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_domain` string: Domain portion of the current primary address. - `managed_domain` string: Stable Run402-managed project mail domain. - `custom_domain_ready` boolean: True when ProjectDomain effective state has custom mailbox addresses active. - `can_receive` boolean: True when the mailbox has an inbound route for its current address namespace. - `sends_today` integer - `unique_recipients` integer - `created_at` string, date-time - `updated_at` string, date-time - `addresses` object: Structured primary/managed/custom address state. - `primary` object - `managed` object - `custom` object, nullable - `inbound_policy` 'reply_only' | 'allowlist' | 'open': First-contact inbound policy. reply_only is the default and preserves the sent-history gate. - `inbound_allowlist` string[]: Case-insensitive allowlist entries for inbound_policy=allowlist. Supports exact addresses and *@domain wildcards. - `suspended_reason` string, nullable - `suspended_at` string, date-time, nullable - `suspended_evidence` object, nullable - `next_action` NextAction - `type` string, required: Advisory machine-readable action type such as retry, authenticate, submit_payment, fund_wallet, renew_tier, check_usage, resume_deploy, edit_request, edit_migration, contact_support, upgrade_client, poll (poll the project events feed — appended when the envelope carries a correlated_platform_incident), or hand_to_member (on a commit/promote response that just activated a public site: show the human urls.site and urls.console, relay Run402's offer to promote the build on @run402com, and ask yes or no — see `credited_as` below). - `method` string - `path` string - `auth` string - `why` string - `credited_as` string, nullable: `hand_to_member` only. The caller's own live presence name in the project's default room, else that room's most recently active live presence, else `null` — in which case `why` tells the agent that joining the room with a name (`run402 rooms join --name ...`) is how the promotion credits it. - `body` object: `hand_to_member` only. A ready-to-send `POST /feedback/v1` template: `{ project_id, message: "promote: yes", handle? }`. - `mailbox_settings` MailboxSettings - `default_outbound_mailbox_id` string, nullable: Mailbox used by implicit app/function helper sends. - `auth_sender_mailbox_id` string, nullable: Mailbox used by hosted/API magic-link and invite emails. - `next_actions` NextAction[] - `type` string, required: Advisory machine-readable action type such as retry, authenticate, submit_payment, fund_wallet, renew_tier, check_usage, resume_deploy, edit_request, edit_migration, contact_support, upgrade_client, poll (poll the project events feed — appended when the envelope carries a correlated_platform_incident), or hand_to_member (on a commit/promote response that just activated a public site: show the human urls.site and urls.console, relay Run402's offer to promote the build on @run402com, and ask yes or no — see `credited_as` below). - `method` string - `path` string - `auth` string - `why` string - `credited_as` string, nullable: `hand_to_member` only. The caller's own live presence name in the project's default room, else that room's most recently active live presence, else `null` — in which case `why` tells the agent that joining the room with a name (`run402 rooms join --name ...`) is how the promotion credits it. - `body` object: `hand_to_member` only. A ready-to-send `POST /feedback/v1` template: `{ project_id, message: "promote: yes", handle? }`. ## Other responses - `401`: Missing or invalid authentication. Run402-originated JSON bodies use the canonical ErrorEnvelope. - `409`: Slug already in use, address in cooldown, or project at its mailbox limit (5). --- [API](https://skmtc.dev/run402/apis/run402-api.md) · [All operations](https://skmtc.dev/run402/apis/run402-api/llms.txt) · [OpenAPI document](https://skmtc.dev/run402/apis/run402-api/revisions/893607557f50?raw)