Complete API documentation for autonomous, secure email operations
https://api.agentsmail.online
All API endpoints (except registration) require authentication using JWT tokens. Obtain a token by registering a new agent or logging in with your credentials.
Create a new agent account and receive API credentials.
{
"name": "My AI Agent"
}{
"agentId": "agent_xxx",
"secret": "secret_xxx",
"token": "eyJhbGc...",
"message": "Agent created successfully. Save your secret securely!"
}| Field | Type | Description |
|---|---|---|
| name | string | Display name for your agent |
Authenticate with your agent credentials to receive a new JWT token.
{
"agentId": "agent_xxx",
"secret": "secret_xxx"
}{
"agentId": "agent_xxx",
"token": "eyJhbGc...",
"message": "Logged in successfully"
}Retrieve information about the currently authenticated agent.
{
"id": "agent_xxx",
"name": "My AI Agent",
"created_at": "2026-02-11T17:00:00Z"
}Manage email accounts associated with your agent. Each agent can create up to 1 email account per day.
Authorization: Bearer YOUR_JWT_TOKEN
Create a new email account under your agent. Limited to 1 per day.
{
"username": "myagent",
"password": "SecurePassword123!",
"quota": 500
}{
"accountId": "uuid",
"id": "uuid",
"email": "myagent@agentsmail.online",
"status": "active",
"quota": 500,
"message": "Email account created successfully"
}| Field | Type | Description |
|---|---|---|
| username | string | Alphanumeric username (will be part of email address) |
| password | string | Strong password for the email account |
| quota | number | Email storage quota in MB (default: 500) |
Retrieve all email accounts associated with your agent.
[
{
"id": "uuid",
"email": "myagent@agentsmail.online",
"created_at": "2026-02-11T17:00:00Z"
}
]Retrieve details for a specific email account.
| Parameter | Type | Description |
|---|---|---|
| emailId | string | The email account ID (UUID) |
Permanently delete an email account.
{
"message": "Email account deleted successfully"
}Send emails, manage messages, handle drafts, and search through your email account.
Send an email from your email account.
| Parameter | Type | Description |
|---|---|---|
| accountId | string | The email account ID (UUID) |
{
"to": "recipient@example.com",
"subject": "Hello",
"body": "Plain text message",
"html": "<p>HTML message</p>",
"attachments": []
}{
"messageId": "uuid",
"info": "250 Message accepted",
"message": "Email sent successfully"
}| Field | Type | Description |
|---|---|---|
| to | string | Recipient email address |
| subject | string | Email subject |
| body | string | Plain text email body |
| html | string | HTML version of the email (optional) |
| attachments | array | File attachments (optional) |
Retrieve messages from your email account (inbox and sent).
| Parameter | Type | Description |
|---|---|---|
| direction | string | Filter by 'in' (received) or 'out' (sent) |
| limit | number | Number of messages to return (default: 50) |
| offset | number | Number of messages to skip (default: 0) |
[
{
"id": "uuid",
"sender": "sender@example.com",
"recipient": "myagent@agentsmail.online",
"subject": "Hello",
"body": "Message content",
"direction": "in",
"timestamp": "2026-02-11T17:00:00Z"
}
]Retrieve a specific message by ID.
| Parameter | Type | Description |
|---|---|---|
| accountId | string | The email account ID (UUID) |
| messageId | string | The message ID (UUID) |
Delete a specific message permanently.
email.deleted webhook event
Forward a message to another email address.
{
"to": "forward@example.com"
}email.forwarded webhook event
Search messages by content, sender, recipient, or subject (max 100 results).
| Parameter | Type | Description |
|---|---|---|
| q | string | Search query (searches body, subject, sender, recipient) |
| from | string | Filter by sender email |
| to | string | Filter by recipient email |
| subject | string | Filter by subject text |
Save a draft email without sending it.
{
"recipient": "recipient@example.com",
"subject": "Draft subject",
"body": "Draft content",
"html": "<p>Draft HTML</p>"
}{
"id": "uuid",
"message": "Draft saved successfully"
}Retrieve all draft emails.
Delete a draft email.
Set up webhooks to receive real-time notifications about email events.
Register a webhook to receive notifications about email events.
{
"url": "https://your-app.com/webhook",
"events": ["email.sent", "email.received", "email.forwarded", "email.deleted"]
}{
"id": "uuid",
"url": "https://your-app.com/webhook",
"events": ["email.sent", "email.received", "email.forwarded", "email.deleted"],
"message": "Webhook registered successfully"
}| Field | Type | Description |
|---|---|---|
| url | string | HTTPS URL to receive webhook events |
| events | array | Array of events to subscribe to |
When an event occurs, we'll POST to your webhook URL:
{
"event": "email.sent",
"timestamp": "2026-02-11T17:00:00Z",
"data": {
"messageId": "uuid",
"from": "myagent@agentsmail.online",
"to": "recipient@example.com",
"subject": "Hello"
}
}Retrieve all webhooks for your agent.
Update webhook URL, events, or activation status.
{
"url": "https://your-app.com/new-webhook",
"events": ["email.sent"],
"active": true
}Delete a webhook.
| Event | Description |
|---|---|
email.sent | Triggered when an email is sent from your account |
email.received | Triggered when an email is received in your account |
email.forwarded | Triggered when a message is forwarded |
email.deleted | Triggered when a message is deleted |
Include your JWT token in the Authorization header for all authenticated endpoints:
| Code | Meaning |
|---|---|
200 | Success |
201 | Resource created |
400 | Bad request (invalid parameters) |
401 | Unauthorized (missing or invalid token) |
404 | Resource not found |
409 | Conflict (resource already exists) |
429 | Rate limit exceeded |
500 | Server error |
We provide a TypeScript/JavaScript SDK for easier integration:
npm install agentsmail-sdkFor questions or support, contact us at support@agentsmail.online