> ## 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.

# SDKs

> Official TypeScript and Python SDK usage examples.

## Install

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

## TypeScript SDK

```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;

await client.sendEmail(
  {
    inboxId,
    to: 'alice@example.com',
    subject: 'Hello',
    text: 'Welcome from EmailAgent'
  },
  { idempotencyKey: 'send-hello-001' }
);

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

## Python SDK

```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"]

client.send_email(
    inbox_id=inbox_id,
    to="alice@example.com",
    subject="Hello",
    text="Welcome from EmailAgent",
    idempotency_key="send-hello-001",
)

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",
    )
```

## Methods

TypeScript:

* `listInboxes()`
* `createInbox(payload, options?)`
* `updateInbox(id, payload, options?)`
* `deleteInbox(id, options?)`
* `sendEmail(payload, options?)`
* `listEmails(params?)`
* `updateEmailRead(id, isRead, options?)`
* `deleteEmail(id, options?)`
* `listDomains()`
* `createDomain(payload, options?)`
* `verifyDomain(id, options?)`
* `deleteDomain(id, options?)`
* `listApiKeys()`
* `createApiKey(payload, options?)`
* `rotateApiKey(id, options?)`
* `revokeApiKey(id, options?)`
* `getMetrics()`

Python:

* `list_inboxes()`
* `create_inbox(...)`
* `update_inbox(...)`
* `delete_inbox(...)`
* `send_email(...)`
* `list_emails(...)`
* `update_email_read(...)`
* `delete_email(...)`
* `list_domains()`
* `create_domain(...)`
* `verify_domain(...)`
* `delete_domain(...)`
* `list_api_keys()`
* `create_api_key(...)`
* `rotate_api_key(...)`
* `revoke_api_key(...)`
* `get_metrics()`

## Error handling

TypeScript SDK throws `EmailAgentApiError` with:

* `status`
* `body`

Python SDK raises `EmailAgentApiError` with:

* `status_code`
* `payload`

For retriable mutations, always pass an idempotency key.