Accounts

Create email addresses and manage mailbox credentials.

Create a Mailbox

POST /api/accounts

Create a new email address on any available system domain.

Request

curl -X POST https://api.mail.cx/api/accounts \
  -H "Content-Type: application/json" \
  -d '{"address":"demo@mail.cx","password":"supersecret"}'

Field	Type	Required	Description
address	string	Yes	Full email address (user@domain)
password	string	Yes	Mailbox password (min 6 chars)

Response 201

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "address": "demo@mail.cx",
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

TIP

The token is returned on creation — you can start using the API immediately without a separate sign-in.

Pro users

Include a Pro API token in the Authorization header to create mailboxes on your verified custom domains. See Pro Accounts for details.

Errors

Status	Error Code	Description
400	invalid_address	Invalid email format or domain
403	account_limit_reached	Mailbox limit reached
409	address_taken	Address already in use

---

Sign In

POST /api/token

Get a new JWT token for an existing mailbox.

Request

curl -X POST https://api.mail.cx/api/token \
  -H "Content-Type: application/json" \
  -d '{"address":"demo@mail.cx","password":"supersecret"}'

Response 200

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "address": "demo@mail.cx",
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Errors

Status	Error Code	Description
401	invalid_credentials	Wrong email or password

---

Get Mailbox Info

GET /api/me

Returns details about the currently authenticated mailbox.

Request

curl https://api.mail.cx/api/me \
  -H "Authorization: Bearer YOUR_TOKEN"

Response 200

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "address": "demo@mail.cx",
  "role": "user",
  "quota": 41943040,
  "used": 12345,
  "created_at": "2025-01-15T10:00:00Z"
}

Field	Type	Description
id	uuid	Account ID
address	string	Email address
role	string	Account role (user or pro)
quota	integer	Storage quota in bytes
used	integer	Storage used in bytes
created_at	string	Account creation timestamp (ISO 8601)

---

Delete Mailbox

DELETE /api/account

Permanently delete the current mailbox and all its messages.

Request

curl -X DELETE https://api.mail.cx/api/account \
  -H "Authorization: Bearer YOUR_TOKEN"

Response 204

No content. The mailbox and all associated data have been permanently deleted.

WARNING

This action is irreversible. All emails will be lost.