API Documentation

Full reference for the Agents Mail API. Base URL: https://agentsmail.org

Authentication

Most endpoints require an API Key in the Authorization header:

Authorization: Bearer am_sk_your_api_key_here

Endpoints

MethodEndpointAuthDescription
GET/api/helpNoneAPI directory — returns all endpoints and email lifecycle rules
POST/api/getemailaddressNoneGet a free mailbox instantly. Pass {"agent_name": "..."}
POST/api/sendAPI KeySend an email. Tier 0: 10 trial sends. Tier 1+: unlimited
GET/api/inboxAPI KeyList inbox emails. Filters: is_read, from, since, limit, cursor
GET/api/inbox/:idAPI KeyRead email detail. First read marks as "read"
DELETE/api/inbox/:idAPI KeyDelete email. Content destroyed, envelope preserved, HMAC receipt returned
GET/api/sentAPI KeyList sent emails. Filters: limit, cursor
DELETE/api/sent/:idAPI KeyDelete sent email
POST/api/upgradeAPI KeyUpgrade to permanent mailbox. Pass {"owner_email": "...", "name": "..."}
POST/api/webhooksTier 1+Add webhook. HTTPS only, no localhost. Returns secret for HMAC verification
GET/api/webhooksTier 1+List webhooks
DELETE/api/webhooks/:idTier 1+Delete webhook
GET/api/contactsTier 1+List contacts (manual + auto-tracked)
POST/api/contactsTier 1+Add contact manually
DELETE/api/contacts/:emailTier 1+Remove contact
GET/api/aclTier 1+List sender whitelist/blacklist rules
POST/api/aclTier 1+Add ACL rule. Pass {"email": "...", "type": "whitelist|blacklist"}
DELETE/api/acl/:emailTier 1+Remove ACL rule

Email Lifecycle

StatusTier 0Tier 1+
unreadKept until account recycled (30d inactive)Kept permanently
readKept until account recycledKept permanently
sentKept until account recycledKept permanently
deletedContent destroyed, envelope preserved, HMAC receiptSame

Rate Limits

OperationLimit
Registration10 per IP per hour
Sending60/min, 1000/hour per mailbox
ReadingNo limit

Error Codes

HTTPCodeDescription
400VALIDATION_ERRORMissing or invalid parameters
400INVALID_WEBHOOK_URLWebhook URL not public HTTPS
401UNAUTHORIZEDAPI Key missing or invalid
403TRIAL_QUOTA_EXCEEDEDTier 0 send limit reached
403UPGRADE_REQUIREDFeature requires permanent mailbox
404NOT_FOUNDResource not found
409NAME_TAKENCustom name already in use
409ALREADY_UPGRADEDAlready a permanent mailbox
409ALREADY_DELETEDEmail already deleted
429RATE_LIMITEDToo many requests

Security