inboxes

Create an inbox

Creates a new inbox with an optional label. Returns 201 with a Location header pointing at the new inbox, or 409 when the plan limit is reached (plan_limit_reached) or after allocation retries are exhausted (conflict).

post/inboxes

Request

  • Base URL: https://dash.mailsocket.app/api/v1
  • URL: https://dash.mailsocket.app/api/v1/inboxes
  • Auth: HTTP bearer

Headers

Idempotency-Keystring

Optional. 1-255 printable ASCII characters (use a UUID). Scoped to the API key that sends it and kept for 24 hours. A retry with the same key and the same body replays the first response (with Idempotent-Replayed: true) and creates nothing new. The same key with a different body or endpoint returns 422 idempotency_key_reused; while the first request is still running, 409 idempotency_in_progress. Stored: 2xx, and 400/404/422 validation errors. Not stored (a retry runs again): outcomes you can fix and retry (402, 403, 409, and 422 domain_not_found_or_unverified), 429 and 5xx. An invalid value, or a body too large to read, returns 400 validation_error.

Request body

labelstring

Optional inbox label.

routing_keystring

Optional custom slug (the local-part of the inbox address). Input is normalized to lowercase BEFORE validation, so callers may pass either case (e.g. MyCustomBox is accepted and stored as mycustombox); the pattern above matches the raw (pre-normalized) input character set. Must start with a letter or digit and contain only A-Za-z, 0-9, _, - after that (3-64 chars total). When omitted, a random routing key is minted. Returns 409 slug_taken if another account already owns it (checked case-insensitively, after lowercasing), or 422 validation_error if it fails the pattern/length constraints or is a reserved key. The reserved-key blocklist applies ONLY when domain is omitted (shared domain); it is not enforced on a custom domain (the owner controls their whole namespace there).

domainstring

Optional public id (dom_...) of a verified custom domain owned by the same account. Omitted (or blank) creates a shared in.inboxpipe.net inbox. Returns 422 domain_not_found_or_unverified if the domain does not exist, is not owned by the caller, or is not verified; 403 byod_disabled if custom domains are not enabled for the account.

publicboolean

Opt-in flag making the inbox's recent messages readable with no auth via GET /public/emails/{email}/messages. Defaults false. Never set it on an inbox that receives real user signups. Shared-domain inboxes only: true combined with a non-blank domain returns 422 public_not_allowed_on_custom_domain. Anyone holding the address can read up to 20 recent messages, including OTPs (never the body or metadata).

metadataobject

Optional correlation metadata (e.g. {"run": "ci-123"}), echoed back on every OWNER-facing read surface (inbox get/list, message poll/latest/wait/batch, webhook payload). NEVER exposed on either anonymous surface (the instant .md endpoints or GET /public/emails/{email}/messages). Must be a JSON object (422 metadata_must_be_object otherwise), at most 4096 bytes of compact UTF-8 JSON and at most 50 top-level keys (422 metadata_too_large otherwise). Omitted defaults to {}.

Response

Inbox created.

Changes

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