Your inboxes, programmable.
Create an API key in your console. Authenticate every request with a Bearer token.
Quick start
curl https://api.inbox.cheap/v1/mailboxes \ -H "Authorization: Bearer YOUR_API_KEY"
| Method | Endpoint | Action |
|---|---|---|
| GET / POST | /v1/mailboxes | List or create addresses |
| DELETE | /v1/mailboxes/{id} | Permanently retire an address |
| GET | /v1/mailboxes/{id}/messages | List received messages |
| GET | /v1/messages/{id}/raw | Download original email |
| GET | /v1/domains | List available domains |
Create an inbox
{"localPart":"project-tests","domain":"159.hk"}Prefixes require 6–63 characters on Free, 5–63 on Plus, and 3–63 on Pro. Destroyed addresses cannot be reused. Free and Plus use 159.hk; Pro also unlocks inbox.cheap.
Batch mailbox creation
Create 1–100 mailboxes per request, within your active plan limit. The operation is atomic: invalid prefixes, reserved names, reused addresses, or insufficient capacity reject the entire batch.
POST https://api.inbox.cheap/v1/mailboxes/batch
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
{"mode":"custom","localParts":["project-one","project-two"],"domain":"159.hk","includeShareLink":true}Generate random inboxes
{"mode":"random","count":5,"domain":"159.hk","includeShareLink":true}Returns HTTP 201 with data and count. Each mailbox includes shareUrl only when includeShareLink is true (default false). The same option works with single creation: POST /v1/mailboxes.
Free: 6–63 characters; Plus: 5–63; Pro: 3–63. Use lowercase letters, digits, dots, underscores, or hyphens; the first character must be a letter or digit. Random prefixes are 12 characters. Only Pro can use @inbox.cheap. Shared links expose the latest 10 messages to anyone holding the link.
Bulk sharing & CSV export
Use your Bearer API key. Both endpoints require POST and operate only on your own inboxes. Existing share links are preserved.
Generate shared links
POST https://api.inbox.cheap/v1/mailboxes/share-links/batch\nContent-Type: application/json\n\n{"mailboxIds":["MAILBOX_ID_1","MAILBOX_ID_2"]}Specify up to 100 IDs, or send {} for all active inboxes. The response contains data and count. Explicitly selected retired inboxes return 410. Foreign inboxes return 404.
Export all inboxes
curl -X POST https://api.inbox.cheap/v1/mailboxes/export.csv \\n -H "Authorization: Bearer YOUR_API_KEY" \\n -o inboxes.csv
CSV includes address, status, message count, creation time (UTC), and read-only URL. Missing links are generated for active inboxes; retired inboxes have blank URLs. Keep exported links private.
Read-only shared inboxes
Each active inbox has a persistent private link on inbox.cheap. Anyone with that link can read its latest 10 messages without signing in. Retiring an inbox disables shared access.
| Method | Endpoint | Action |
|---|---|---|
| GET | /v1/mailboxes/{id}/share-link | Get or initialize the persistent URL |
| POST | /v1/mailboxes/{id}/share-link | Reset the URL with {"rotate":true} |
{"mailboxId":"…","url":"https://inbox.cheap/s/…","readOnly":true,"messageLimit":10}Requires the owning account’s Bearer API key. Resetting a link immediately revokes the old URL. Treat the link as a password.