Authentication

Mail.td uses bearer token authentication on every API endpoint. One header, one token type:

Authorization: Bearer td_xxxxxxxxxxxxxxxxxxxx

The token is issued from the Dashboard, used on every request, and long-lived until you revoke it. Tiering (trial vs. Pro) is a property of your account, not of your token — the same td_ token works across both tiers, and your quota simply changes when you activate Pro.

Getting a token

1. Sign in at mail.td/pro/login with Google or GitHub. An account is created automatically on first sign-in — you start on the trial tier.
2. Open the Dashboard and create an API token.
3. Copy the token immediately. It starts with td_ and is shown only once.

Tiers

Tier	How to get it	Ops quota	Features
Trial	Any registered account	Lower monthly cap, 4 req/s	Core API
Pro	Activate a subscription	100,000 ops/mo, 10 req/s	Core API + custom domains, webhooks, SMTP sandbox, multiple tokens

Using the token

Pass it as a bearer credential on every request:

curl https://api.mail.td/api/user/me \
  -H "Authorization: Bearer td_xxxxxxxxxxxxxxxxxxxx"

Tokens can be revoked programmatically via DELETE /api/user/tokens/:id or from the dashboard. Revocation is immediate.

Endpoints without auth

One endpoint — a discovery helper — can be called without a bearer token:

	Endpoint	Purpose
GET	/api/domains	Browse available system domains before you sign up.

Every other endpoint, including POST /api/accounts, requires a valid td_ bearer token.

Error responses

An invalid or expired token returns 401 Unauthorized:

{"error": "invalid_or_expired_token"}

A missing token on a protected endpoint returns 401:

{"error": "unauthorized"}

Security

• Always use HTTPS. The API rejects plain HTTP.
• Never embed a token in client-side JavaScript or a mobile binary.
• Rotate tokens periodically or when you change team membership.
• Revoke tokens immediately if leaked; a new one can be minted in seconds.