Skip to main content

​
0. Install SDKs (optional)

npm install emailagent-sdk@0.1.0
pip install emailagent-sdk==0.1.0
Full SDK usage guide: SDKs.

​
1. Authenticate

Use a bearer API key from the dashboard. 
curl -X GET "https://api.emailagent.dev/api/v1/inboxes" \
  -H "Authorization: Bearer <api_key>"

​
2. Create inbox

curl -X POST "https://api.emailagent.dev/api/v1/inboxes" \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: create-inbox-agent-1" \
  -d '{
    "localPart": "agent-1",
    "displayName": "Agent One"
  }'

​
3. Send email

curl -X POST "https://api.emailagent.dev/api/v1/emails/send" \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: send-welcome-001" \
  -d '{
    "inboxId": "<inbox_uuid>",
    "to": "alice@example.com",
    "subject": "Hello",
    "text": "Welcome from your AI agent"
  }'

​
4. List and mark inbound email

curl -X GET "https://api.emailagent.dev/api/v1/emails?inboxId=<inbox_uuid>" \
  -H "Authorization: Bearer <api_key>"

curl -X PATCH "https://api.emailagent.dev/api/v1/emails/<email_uuid>/read" \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: mark-read-001" \
  -d '{"isRead": true}'

​
5. SDK examples

import { EmailAgentClient } from 'emailagent-sdk';

const client = new EmailAgentClient({
  apiKey: process.env.EMAILAGENT_API_KEY!,
  baseUrl: 'https://api.emailagent.dev'
});

const inboxes = await client.listInboxes();
const inboxId = inboxes.data[0].id;
const emails = await client.listEmails({ inboxId });
if (emails.data.length) {
  await client.updateEmailRead(emails.data[0].id, true, { idempotencyKey: 'mark-read-001' });
}

from emailagent_sdk import EmailAgentClient

client = EmailAgentClient(api_key="<api_key>", base_url="https://api.emailagent.dev")
inboxes = client.list_inboxes()
inbox_id = inboxes["data"][0]["id"]
emails = client.list_emails(inbox_id=inbox_id)
if emails["data"]:
    client.update_email_read(
        email_id=emails["data"][0]["id"],
        is_read=True,
        idempotency_key="mark-read-001",
    )

​
6. Shared-domain inbound route (manual setup)

For shared-domain inboxes (for example agent@emailagent.dev), configure this in Mailgun Routes:
  • Expression: match_recipient('.*@emailagent.dev')
  • Action 1: forward('https://app.emailagent.dev/webhooks/mailgun/inbound')
  • Action 2: stop()
Also set MAILGUN_WEBHOOK_SIGNING_KEY in app environment to enforce webhook signature validation. Expected successful webhook response: 
{"ok": true}

​
7. Inbound troubleshooting

Webhook responseMeaningAction
401Invalid signatureVerify MAILGUN_WEBHOOK_SIGNING_KEY matches Mailgun webhook signing key
202 with ignored: trueRecipient does not map to active inboxCreate/check inbox local part and domain in app
200 with duplicate: trueDuplicate event receivedNo action needed; dedupe is working

​
8. Inbound smoke test

  1. Create inbox agent@emailagent.dev in app.
  2. Send email from external mailbox to that inbox.
  3. Confirm message appears in dashboard inbox view.
  4. Confirm same message appears via GET /api/v1/emails?inboxId=<inbox_uuid>.

​
9. Check metrics

curl -X GET "https://api.emailagent.dev/api/v1/metrics" \
  -H "Authorization: Bearer <api_key>"

​
10. MCP (optional)

If your agent platform supports MCP, use the official MCP setup guide: