> ## Documentation Index
> Fetch the complete documentation index at: https://docs.emailagent.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Create an API key, send email, and consume inbound email records.

## 0. Install SDKs (optional)

```bash theme={null}
npm install emailagent-sdk@0.1.0
pip install emailagent-sdk==0.1.0
```

Full SDK usage guide: [SDKs](./sdks).

## 1. Authenticate

Use a bearer API key from the dashboard.

```bash theme={null}
curl -X GET "https://api.emailagent.dev/api/v1/inboxes" \
  -H "Authorization: Bearer <api_key>"
```

## 2. Create inbox

```bash theme={null}
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

```bash theme={null}
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

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

```bash theme={null}
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

```ts theme={null}
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' });
}
```

```python theme={null}
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:

```json theme={null}
{"ok": true}
```

## 7. Inbound troubleshooting

| Webhook response             | Meaning                                | Action                                                                   |
| ---------------------------- | -------------------------------------- | ------------------------------------------------------------------------ |
| `401`                        | Invalid signature                      | Verify `MAILGUN_WEBHOOK_SIGNING_KEY` matches Mailgun webhook signing key |
| `202` with `ignored: true`   | Recipient does not map to active inbox | Create/check inbox local part and domain in app                          |
| `200` with `duplicate: true` | Duplicate event received               | No 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

```bash theme={null}
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:

* [MCP overview](https://docs.emailagent.dev/mcp/index)
* [Claude Desktop](https://docs.emailagent.dev/mcp/claude-desktop)
* [Cursor](https://docs.emailagent.dev/mcp/cursor)