Security

Authentication

AgentEmail uses API keys to authenticate requests. All persistent inbox operations require a valid key.

Getting Your API Key

API keys are managed in your Dashboard. Each key is prefixed with ak_ for easy identification.

Free tier: Temporary inboxes don't require an API key. Use the public endpoints for quick testing.

Using Your API Key

Include your API key in the Authorization header with a Bearer prefix:

cURL

curl -X POST https://api.agentemail.email/api/v1/inboxes \
  -H "Authorization: Bearer ak_your_api_key" \
  -H "Content-Type: application/json"

SDK Authentication

When using an SDK, pass the API key during client initialization:

PythonNode.js

from agentemail import AgentEmail

# Initialize client with API key
client = AgentEmail(api_key="ak_your_api_key")

# Or use environment variable (recommended)
# export AGENTEMAIL_API_KEY=ak_your_api_key
client = AgentEmail()

Temporary Inbox Tokens

Temporary inboxes use short-lived tokens instead of API keys. A token is returned when you create a temporary inbox and is valid for the lifetime of that inbox (default 60 minutes).

Include the token in the X-Inbox-Token header:

cURL

curl https://api.agentemail.email/api/v1/public/inbox/<inbox_id>/messages \
  -H "X-Inbox-Token: temp_xYz9kL..."

Security Best Practices

Use environment variables

Never hardcode API keys in source code. Use AGENTEMAIL_API_KEY environment variable.

Rotate regularly

Generate new keys periodically from the Dashboard. Old keys can be revoked instantly.

Least privilege

Use temporary inbox tokens when you don't need persistent access.

Server-side only

Never expose API keys in client-side code, browser requests, or public repositories.