Agent Email API

Send and receive email from your agent's dedicated address (agent-{id}@agent.agnic.ai).

Base URL: https://api.agnic.ai

Authentication: All endpoints use authenticateFlexible — pass either Authorization: Bearer <oauth_token> or X-Agnic-Token: <api_token>.

Get Email Alias

Retrieve the agent's email alias information.

GET /api/agent/email

Response:

{
  "hasEmail": true,
  "emailAddress": "[email protected]",
  "displayName": "My Agent",
  "walletAddress": "0xe38b20d6eb4dbd04b7f13fa8f9b6352d3824a0e1",
  "agentId": 396,
  "isActive": true,
  "createdAt": "2026-04-03T13:14:46.312Z"
}

Example:

curl -H "X-Agnic-Token: agnic_tok_YOUR_TOKEN" \
  https://api.agnic.ai/api/agent/email

Create Email Alias

Create or retrieve an email alias for the agent. Idempotent — returns existing alias if one exists.

POST /api/agent/email

Request Body:

Field	Type	Required	Description
`displayName`	string	No	Display name for outgoing emails

Example:

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

Get Inbox

Fetch the agent's email inbox (newest first).

GET /api/agent/email/inbox?limit=20&offset=0

Query Parameters:

Parameter	Type	Default	Description
`limit`	number	20	Max messages to return (max: 100)
`offset`	number	0	Pagination offset

Response:

{
  "emailAddress": "[email protected]",
  "messages": [
    {
      "id": "aem_1775225354572_apc7y7",
      "direction": "inbound",
      "from": "[email protected]",
      "to": "[email protected]",
      "subject": "Re: Hello from Agent 396",
      "bodyText": "Hey agent, how are you?",
      "bodyHtml": "<div>Hey agent, how are you?</div>",
      "isRead": false,
      "threadId": null,
      "createdAt": "2026-04-03T14:09:14.712Z"
    }
  ],
  "limit": 20,
  "offset": 0
}

Example:

curl -H "X-Agnic-Token: agnic_tok_YOUR_TOKEN" \
  "https://api.agnic.ai/api/agent/email/inbox?limit=10"

Send Email

Send an email from the agent's address.

POST /api/agent/email/send

Request Body:

Field	Type	Required	Description
`to`	string or string[]	Yes	Recipient email address(es)
`subject`	string	Yes	Email subject line
`body`	string	Yes	Email body (plain text)

Response:

{
  "sent": true,
  "messageId": "3e23958a-9ec3-4d2a-9ec3-8270e015bf29",
  "from": "[email protected]",
  "to": "[email protected]",
  "subject": "Hello from Agent 396"
}

Example:

curl -X POST \
  -H "X-Agnic-Token: agnic_tok_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"to": "[email protected]", "subject": "Hello", "body": "From my agent"}' \
  https://api.agnic.ai/api/agent/email/send

Reply to Message

Reply to an inbox message. Maintains email threading.

POST /api/agent/email/reply

Request Body:

Field	Type	Required	Description
`messageId`	string	Yes	ID of the message to reply to
`body`	string	Yes	Reply body (plain text)

Response:

{
  "sent": true,
  "messageId": "8a2b3c4d-...",
  "from": "[email protected]",
  "to": "[email protected]",
  "subject": "Re: Hello from Agent 396"
}

Example:

curl -X POST \
  -H "X-Agnic-Token: agnic_tok_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"messageId": "aem_1775225354572_apc7y7", "body": "Thanks for your reply!"}' \
  https://api.agnic.ai/api/agent/email/reply

Inbound Webhook

Resend sends inbound email events to this endpoint. Not called directly by users.

POST /webhook/email/inbound

Headers: Svix signature headers (svix-id, svix-timestamp, svix-signature)

Payload:

{
  "type": "email.received",
  "created_at": "2026-04-03T13:19:34.000Z",
  "data": {
    "email_id": "8686f5ba-ae04-4d4f-a44a-d466af13bc9b",
    "from": "[email protected]",
    "to": ["[email protected]"],
    "subject": "Re: Hello from Agent 396",
    "message_id": "<[email protected]>"
  }
}

The server fetches the full email body via GET /emails/receiving/{email_id} from the Resend API.

Error Responses

Status	Error	Description
400	"No active agent found"	Complete onboarding first
400	"Missing required fields"	Check required fields in request body
404	"No email alias found"	Create alias with `POST /api/agent/email`
502	"Failed to send email"	Resend API error
503	"Email sending not configured"	`RESEND_API_KEY` not set on server

Agent Email

On this page