API Reference

Authentication

Register an account, obtain JWT tokens, and create API keys for programmatic access. Temporary inbox endpoints require no authentication.

Auth Methods

JWT

Short-lived token obtained via login. Pass as Authorization: Bearer <token>. Expires after 72 hours.

API Key

Long-lived key for agents and automation. Pass as X-API-Key: ak_.... Does not expire — revoke manually when needed.

None

Public endpoints (/api/v1/public/*) require no authentication. Used for temporary inboxes.

User Object

Field	Type	Description
id	uuid	Unique user identifier
email	string	User email address
name	string	Display name
plan	string	Current plan (free, pro, etc.)
created_at	timestamp	Account creation time

Account

POST/api/v1/auth/register

Register

Create a new user account. Returns a JWT token and user object.

Request Body

emailstring*

Email address

passwordstring*

Password (min 8 characters)

namestring*

Display name

cURL

curl -X POST https://api.agentemail.email/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{"email":"dev@example.com","password":"securepass","name":"Dev"}'

Response

{
  "success": true,
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIs...",
    "user": {
      "id": "user-uuid...",
      "email": "dev@example.com",
      "name": "Dev",
      "plan": "free"
    }
  }
}

POST/api/v1/auth/login

Login

Authenticate with email and password. Returns a JWT token valid for 72 hours.

Request Body

emailstring*

Email address

passwordstring*

Password

cURL

curl -X POST https://api.agentemail.email/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"dev@example.com","password":"securepass"}'

Response

{
  "success": true,
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIs...",
    "user": { ... }
  }
}

API Keys

POST/api/v1/auth/api-keysJWT

Create API Key

Generate a new API key. The raw key is returned only once — store it securely.

Request Body

namestring*

Descriptive name for the key (e.g. "my-agent")

cURL

curl -X POST https://api.agentemail.email/api/v1/auth/api-keys \
  -H "Authorization: Bearer eyJhbG..." \
  -H "Content-Type: application/json" \
  -d '{"name":"my-agent"}'

Response

{
  "success": true,
  "data": {
    "api_key": {
      "id": "key-uuid...",
      "name": "my-agent",
      "key_prefix": "ak_7x9f"
    },
    "key": "ak_7x9fK2mN..."
  }
}

GET/api/v1/auth/api-keysJWT

List API Keys

List all API keys for the authenticated user. The raw key value is not returned — only the prefix.

cURL

curl https://api.agentemail.email/api/v1/auth/api-keys \
  -H "Authorization: Bearer eyJhbG..."

Response

{
  "success": true,
  "data": [{
    "id": "key-uuid...",
    "name": "my-agent",
    "key_prefix": "ak_7x9f",
    "last_used": "2026-03-27T14:00:00Z"
  }]
}

DELETE/api/v1/auth/api-keys/{id}JWT

Delete API Key

Revoke an API key. Any requests using this key will immediately fail.

Path Parameters

iduuid

API Key ID

cURL

curl -X DELETE https://api.agentemail.email/api/v1/auth/api-keys/{id} \
  -H "Authorization: Bearer eyJhbG..."