---
search:
  tags:
    - Inboxes
    - POST
seo:
  description: >-
    An address that receives into threads, on one of your verified domains
    (receiving on, or… Reference for the POST /inboxes endpoint in the
    BillionSend API.
sidebar:
  label: Create an inbox
  badge: POST
title: Create an inbox
type: openapi-operation
---
An address that receives into threads, on one of your verified domains (receiving on, or forwarding: true) or, with email_address omitted, an address on the shared inbox domain that needs no DNS: username names it, or it is random. domain_id takes a row of GET /domains instead of email_address: the team's shared subdomain, or one of your domains with username. It never expires unless expires_in says so. Returns the full inbox. BillionSend extensions: username, domain_id, kind (agent by default), expires_in and safety.

`POST /inboxes`

**Request body** (`application/json`)

- `email_address` (string) — An address on one of your verified domains; it needs receiving on unless forwarding is true. BillionSend extension: omitted, the inbox gets an address on the shared inbox domain (no DNS), named by username or random, unless domain\_id names one of your domains.
- `domain_id` (string<uuid>) — BillionSend extension: the id of a GET /domains row, instead of email\_address. The team's subdomain of the shared domain (the row with shared: true) is the same as leaving email\_address out; one of your verified domains needs username, the part before the @.
- `username` (string) — BillionSend extension: with email\_address omitted, the part before the @ of the shared-domain address, trimmed and lowercased: 1-64 letters, digits, dots, hyphens and underscores, starting and ending with a letter or digit, never cut short. Reserved names (postmaster, abuse, admin, security, support, noreply, no-reply, billing, hostmaster, webmaster, mailer-daemon, root, compared without dots, hyphens and underscores), the fwd- prefix and brand look-alikes answer 422, and one already in use 409. A chosen name is reviewed first: 503 with retry-after while that review is unavailable. Omitted: a random one. With a domain\_id of one of your domains, it is the part before the @ there, required, under email\_address's rule.
- `name` (string) — Internal name, 1-320 characters, so any address fits. Defaults to email\_address.
- `from_name` (string) — The name recipients see, a plain name (not "Name \<email\>"); "" leaves it unset. On the shared domain it may not imitate a brand, and it is reviewed like username.
- `forwarding` (boolean) — Receive without an MX record: mail forwarded to the inbox's receiving\_address lands in it
- `kind` (string) — BillionSend extension: agent (default; threads, screening, drafts that wait for approval) or human (a team mailbox)
- `expires_in` (string | null) — BillionSend extension: a lifetime counted from now, "1h" to "365d"; omitted or null, the inbox never expires. A shared-domain inbox left unused for 90 days (no mail in or out, no API calls on it) is deleted either way.
- `safety` (InboxSafetyPatch) — BillionSend extension: safety rules over the kind's defaults

Request body example:

```json
{
  "email_address": "string",
  "domain_id": "b2f7354f-b74d-4332-ab10-1a5e3c56466c",
  "username": "string",
  "name": "string",
  "from_name": "string",
  "forwarding": true,
  "kind": "agent",
  "expires_in": "string",
  "safety": {
    "accept_from": "anyone",
    "allowlist": [
      "string"
    ],
    "owner_addresses": [
      "string"
    ],
    "screening": true,
    "extract_codes": true,
    "send_policy": "reply_only",
    "require_approval": true,
    "private_codes": true,
    "send_cap": 0,
    "forward_to": [
      "string"
    ]
  }
}
```

**Responses**

- `201` — Inbox created
- `401` — Missing, malformed, unknown or revoked API key
- `403` — The plan's inbox limit, or a restricted API key
- `409` — The address is already used by an inbox
- `422` — Validation error
- `429` — Too many inboxes created in the last hour, or too many names reviewed or refused on the shared domain today, or the rate limit (rate\_limit\_exceeded, with Retry-After)
- `503` — A chosen username or from\_name on the shared domain can't be reviewed right now, or the team's subdomain on the shared domain is still waiting for its name review; retry-after says when to try again

Response example, 201:

```json
{
  "object": "inbox",
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "name": "string",
  "email_address": "string",
  "domain_id": "b2f7354f-b74d-4332-ab10-1a5e3c56466c",
  "receiving_address": "string",
  "from_name": "string",
  "unread": 0,
  "drafts": 0,
  "last_received": "string",
  "created_at": "string",
  "updated_at": "string",
  "kind": "agent",
  "shared": true,
  "expires_at": "string",
  "quarantined": 0,
  "pending_approval": 0
}
```
