Accounts

Create and manage email accounts. All endpoints require Authorization: Bearer <token>.

Create an Account

POST /api/accounts

Creates an email account. Returns the account ID and address. All subsequent operations use the same API token.

Request:

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

Field	Type	Required	Description
address	string	Yes	Email address (local@domain)
password	string	Yes	Password (min 6 characters)

Response (201):

{
  "id": "a1b2c3d4-e5f6-7890-abcd-1234567890ab",
  "address": "demo@mail.td"
}

INFO

Save the id (account ID). It is used as {account_id} in all subsequent API paths.

{account_id} is the email address

All API paths that contain {account_id} accept the email address directly (e.g. demo@mail.td). UUID format is also supported.

Pro accounts can create addresses on custom domains and get higher storage quotas.

Errors:

Code	Error	Description
400	invalid_address	Malformed email address
400	invalid_domain	Domain not available
400	password_too_short	Password under minimum length
403	account_limit_reached	Quota exceeded
409	address_taken	Address already in use

Get Account Info

GET /api/accounts/{account_id}

Returns account details including storage usage.

Response (200):

{
  "id": "a1b2c3d4-...",
  "address": "demo@mail.td",
  "role": "user",
  "quota": 41943040,
  "used": 1234567,
  "created_at": "2025-01-15T10:30:00Z"
}

Field	Type	Description
quota	integer	Storage limit in bytes
used	integer	Current storage usage in bytes

Delete Account

DELETE /api/accounts/{account_id}

Permanently deletes the account and all its messages. This action is irreversible.

Response: 204 No Content

Reset Password

PUT /api/accounts/{account_id}/reset-password

Resets the account's authentication credentials. All existing tokens are invalidated.

Request:

{
  "password": "newpassword123"
}

Response (200):

{
  "message": "password_reset"
}

Access Control

Your API token (td_...) can access any account owned by your Pro user. Attempting to access an account you don't own returns 404 Not Found.