---
title: "Create a mailbox export"
method: POST
path: "/mailboxes/{id}/exports"
tags: ["Mailboxes"]
---

# Create a mailbox export

`POST /mailboxes/{id}/exports`

## Request

- Base URL: `https://shipmail.to/api/v1`
- URL: `https://shipmail.to/api/v1/mailboxes/{id}/exports`
- Auth: one of:
  - HTTP bearer
  - OAuth 2 (authorization code, authorization URL `https://shipmail.to/api/auth/oauth2/authorize`, token URL `https://shipmail.to/api/auth/oauth2/token`)

Queue a fail-closed ZIP snapshot of one mailbox. If a completed export for this mailbox is younger than 15 minutes, that export is returned with status 200 instead of creating a new one. Archived mailboxes reuse their exact current billing snapshot without restoring the mailbox. Subscribe to the mailbox.export.completed and mailbox.export.failed webhook events instead of polling the returned export. At most 24 exports per mailbox per rolling 24 hours; beyond that the endpoint returns 429 with Retry-After. Exports are for backups, not for polling for new mail: use GET /messages, GET /mailboxes/{id}/inbox/messages, or webhooks to keep inbound mail in sync.

## Headers

- `X-Shipmail-Organization` string

## Response `200`

Existing active export, or a completed export younger than 15 minutes, returned.

- MailboxExport
  - `object` 'mailbox_export', required
  - `id` string, required
  - `mailbox_id` string, required
  - `status` 'pending' | 'processing' | 'completed' | 'failed' | 'expired', required
  - `format` 'zip', required
  - `format_version` integer, required
  - `file_size` integer, nullable, required
  - `message_count` integer, nullable, required
  - `folder_count` integer, nullable, required
  - `error_code` 'source_unavailable' | 'snapshot_changed' | 'export_failed' | 'null', nullable, required
  - `download_url` string, uri, nullable, required
  - `download_url_expires_at` string, date-time, nullable, required
  - `expires_at` string, date-time, nullable, required
  - `created_at` string, date-time, required
  - `started_at` string, date-time, nullable, required
  - `completed_at` string, date-time, nullable, required

## Other responses

- `201`: Completed export created by reusing a compatible archived snapshot.
- `202`: Mailbox export queued.
- `401`: Authentication failed.
- `403`: Insufficient permissions.
- `404`: Resource not found.
- `409`: Resource conflict.
- `429`: Rate limit exceeded.

---

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