Agent Email | Agnic Docs

Dedicated email addresses for AI agents — send, receive, and manage email programmatically.

Every agent gets a unique address agent-{id}@agent.agnic.ai. Use these endpoints to manage the alias, check the inbox, send emails, and reply to messages.

GET/api/agent/email

Get Agent Email Alias

Returns the agent's dedicated email address and alias metadata. If no alias has been created yet, returns `{ "hasEmail": false }`.

Auth:ApiTokenOAuth2

Responses

200Email alias info

Field	Type	Description
hasEmail	boolean	Whether an email alias exists for this agent
emailAddress	string<email>	The agent's dedicated email address (agent-{id}@agent.agnic.ai)
displayName	string	Display name used in the From header for outgoing emails
walletAddress	string	The agent's on-chain wallet address
agentId	integer	The agent's numeric ID
isActive	boolean
createdAt	string<date-time>

401Unauthorized - invalid or missing authentication

Field	Type	Description
error	string
error_description	string
message	string

500Internal server error

object — circular

Example (cURL)

curl -X GET 'https://api.agnic.ai/api/agent/email' \
  -H 'X-Agnic-Token: YOUR_TOKEN'

POST/api/agent/email

Create Agent Email Alias

Creates a dedicated email alias for the agent (`agent-{id}@agent.agnic.ai`). Idempotent — returns the existing alias if one already exists. Requires the agent to be onboarded (status `active`).

Auth:ApiTokenOAuth2

Request body

Field	Type	Description
displayName	string	Display name shown in outgoing email From header (optional)

Example request

{
  "displayName": "My Research Agent"
}

Responses

200Email alias created or returned

Field	Type	Description
hasEmail	boolean	Whether an email alias exists for this agent
emailAddress	string<email>	The agent's dedicated email address (agent-{id}@agent.agnic.ai)
displayName	string	Display name used in the From header for outgoing emails
walletAddress	string	The agent's on-chain wallet address
agentId	integer	The agent's numeric ID
isActive	boolean
createdAt	string<date-time>

400No active agent found

Field	Type	Description
error	string
error_description	string
message	string

401Unauthorized - invalid or missing authentication

object — circular

500Internal server error

object — circular

Example (cURL)

curl -X POST 'https://api.agnic.ai/api/agent/email' \
  -H 'X-Agnic-Token: YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"displayName":"My Research Agent"}'

GET/api/agent/email/inbox

Get Email Inbox

Returns the agent's inbox — both inbound messages received and outbound messages sent. Messages are retained for 30 days.

Auth:ApiTokenOAuth2

query parameters

Name	Type	Description
limit	integer default: 20	Max messages to return
offset	integer default: 0	Pagination offset

Responses

200Inbox messages

Field

Type

Description

emailAddress

string<email>

messages

object[]

show nested schema

array of

Field	Type	Description
id	string	Unique message ID (use this for reply) example: "aem_1775222237594_v4gwcj"
direction	"inbound" \| "outbound"
from	string<email>
to	string<email>
subject	string
bodyText	string
bodyHtml	string
isRead	boolean
threadId	string
createdAt	string<date-time>

limit

integer

offset

integer

401Unauthorized - invalid or missing authentication

Field	Type	Description
error	string
error_description	string
message	string

404No email alias found

object — circular

500Internal server error

object — circular

Example (cURL)

curl -X GET 'https://api.agnic.ai/api/agent/email/inbox' \
  -H 'X-Agnic-Token: YOUR_TOKEN'

POST/api/agent/email/send

Send Email

Sends an email from the agent's dedicated address (`agent-{id}@agent.agnic.ai`). The outbound message is stored in the agent's inbox for reference.

Auth:ApiTokenOAuth2

Request body *

Field	Type	Description
to*	string<email>	Recipient email address
subject*	string	Email subject line
body*	string	Email body (plain text)

Example request

{
  "to": "[email protected]",
  "subject": "Research Results",
  "body": "Here are the findings from my analysis..."
}

Responses

200Email sent

Field	Type	Description
sent	boolean
messageId	string	Resend message ID
from	string<email>
to	string<email>
subject	string

400Missing required fields

Field	Type	Description
error	string
error_description	string
message	string

401Unauthorized - invalid or missing authentication

object — circular

404No email alias found

object — circular

500Internal server error

object — circular

502Email provider error

object — circular

503Email sending not configured

object — circular

Example (cURL)

curl -X POST 'https://api.agnic.ai/api/agent/email/send' \
  -H 'X-Agnic-Token: YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"to":"[email protected]","subject":"Research Results","body":"Here are the findings from my analysis..."}'

POST/api/agent/email/reply

Reply to Email

Replies to a message in the agent's inbox. Automatically sets `In-Reply-To` and `References` headers to maintain email thread continuity. Also marks the original message as read.

Auth:ApiTokenOAuth2

Request body *

Field	Type	Description
messageId*	string	ID of the inbox message to reply to (from GET /api/agent/email/inbox) example: "aem_1775222237594_v4gwcj"
body*	string	Reply body (plain text)

Example request

{
  "messageId": "aem_1775222237594_v4gwcj",
  "body": "Thank you, confirmed!"
}

Responses

200Reply sent

Field	Type	Description
sent	boolean
messageId	string	Resend message ID
from	string<email>
to	string<email>
subject	string

400Missing required fields

Field	Type	Description
error	string
error_description	string
message	string

401Unauthorized - invalid or missing authentication

object — circular

404No email alias or original message not found

object — circular

500Internal server error

object — circular

502Email provider error

object — circular

503Email sending not configured

object — circular

Example (cURL)

curl -X POST 'https://api.agnic.ai/api/agent/email/reply' \
  -H 'X-Agnic-Token: YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"messageId":"aem_1775222237594_v4gwcj","body":"Thank you, confirmed!"}'