---
title: "Create a mailbox"
method: POST
path: "/mailboxes"
tags: ["Mailboxes"]
---

# Create a mailbox

`POST /mailboxes`

## Request

- Base URL: `https://api.tinysend.com/v1`
- URL: `https://api.tinysend.com/v1/mailboxes`
- Auth: HTTP bearer

## Request body

- object
  - `address` string: Full email address (slug@domain). Optional for disposable mailboxes — a readable address (e.g. swift-otter@tinysend.com) is auto-generated when omitted.
  - `name` string
  - `type` 'persistent' | 'disposable' | 'proxy'
  - `config` object
  - `ttl` union: Lifetime for a disposable mailbox: a duration shorthand ("1h", "24h", "7d") or a number of seconds. Max 30 days. Alternative to expires_at; defaults to 24h.
    - string
    - number
  - `expires_at` string, date-time: ISO 8601 expiry for disposable mailboxes (max 30 days out). Alternative to ttl.
  - `domain` string: Domain for an auto-generated disposable address. Defaults to tinysend.com.
  - `list_id` string: Link mailbox to existing list

## Response `201`

Created mailbox

- MailboxDetail
  - `id` string, required
  - `address` string, required
  - `local_part` string, required
  - `domain` string, required
  - `name` string, nullable, required
  - `type` string, required
  - `status` string, required
  - `list_id` string, nullable, required
  - `config` object, nullable, required
  - `expires_at` string, nullable, required
  - `created_at` string, required

## Other responses

- `422`: Validation error

---

[API](https://skmtc.dev/tinysend/apis/tinysend-api.md) · [All operations](https://skmtc.dev/tinysend/apis/tinysend-api/llms.txt) · [OpenAPI document](https://skmtc.dev/tinysend/apis/tinysend-api/revisions/2dc68ac83332?raw)