### Install Project Dependencies (Bash)

Source: https://github.com/agentmail-to/agentmail-node/blob/main/CONTRIBUTING.md

Installs all necessary dependencies for the project using the pnpm package manager. Ensure Node.js 20+ and pnpm are installed.

```bash
pnpm install
```

--------------------------------

### Install Agentmail Node Package

Source: https://github.com/agentmail-to/agentmail-node/blob/main/README.md

Installs the Agentmail Node.js package using npm. This is the first step to using the library in your project.

```shell
npm i -s agentmail
```

--------------------------------

### Initialize Agentmail Client in TypeScript

Source: https://github.com/agentmail-to/agentmail-node/blob/main/README.md

Demonstrates how to instantiate the AgentMailClient in TypeScript. Requires an API key for authentication. The client is then used to interact with the Agentmail API, shown here with an example of creating an inbox.

```typescript
import { AgentMailClient } from "agentmail";

const client = new AgentMailClient({ apiKey: "YOUR_API_KEY" });
await client.inboxes.create(undefined);
```

--------------------------------

### Custom Winston Logger for AgentMail SDK

Source: https://github.com/agentmail-to/agentmail-node/blob/main/README.md

Provides an example of integrating the Winston logging library with the AgentMail SDK by creating a compatible ILogger object.

```typescript
import winston from 'winston';
import { logging } from "agentmail";

const winstonLogger = winston.createLogger({...});

const logger: logging.ILogger = {
    debug: (msg, ...args) => winstonLogger.debug(msg, ...args),
    info: (msg, ...args) => winstonLogger.info(msg, ...args),
    warn: (msg, ...args) => winstonLogger.warn(msg, ...args),
    error: (msg, ...args) => winstonLogger.error(msg, ...args),
};
```

--------------------------------

### Save Binary Response to File in Deno

Source: https://github.com/agentmail-to/agentmail-node/blob/main/README.md

Shows how to save binary responses to files within the Deno runtime. Examples include using `ReadableStream` with `pipeTo`, and writing `ArrayBuffer`, `Blob`, and `Uint8Array` data using `Deno.writeFile`.

```typescript
const response = await client.domains.getZoneFile(...);

const stream = response.stream();
const file = await Deno.open('path/to/file', { write: true, create: true });
await stream.pipeTo(file.writable);
```

```typescript
const response = await client.domains.getZoneFile(...);

const arrayBuffer = await response.arrayBuffer();
await Deno.writeFile('path/to/file', new Uint8Array(arrayBuffer));
```

```typescript
const response = await client.domains.getZoneFile(...);

const blob = await response.blob();
const arrayBuffer = await blob.arrayBuffer();
await Deno.writeFile('path/to/file', new Uint8Array(arrayBuffer));
```

```typescript
const response = await client.domains.getZoneFile(...);

const bytes = await response.bytes();
await Deno.writeFile('path/to/file', bytes);
```

--------------------------------

### Download Binary Response as Blob using Bytes (TypeScript)

Source: https://github.com/agentmail-to/agentmail-node/blob/main/README.md

This example shows how to obtain binary data from a response as a Uint8Array (bytes), convert it into a Blob, and then trigger a file download. This method is suitable for responses where binary data is directly accessible as byte arrays.

```typescript
const response = await client.domains.getZoneFile(...);

const bytes = await response.bytes();
const blob = new Blob([bytes]);
const url = URL.createObjectURL(blob);

// trigger download
const a = document.createElement('a');
a.href = url;
a.download = 'filename';
a.click();
URL.revokeObjectURL(url);
```

--------------------------------

### Convert Binary Response to Text using Blob (TypeScript)

Source: https://github.com/agentmail-to/agentmail-node/blob/main/README.md

This example shows how to convert a Blob obtained from a response directly into text using the Blob.text() method. This is a straightforward approach for handling binary responses that can be represented as Blobs and contain text data.

```typescript
const response = await client.domains.getZoneFile(...);

const blob = await response.blob();
const text = await blob.text();
```

--------------------------------

### Save Binary Response to File in Node.js

Source: https://github.com/agentmail-to/agentmail-node/blob/main/README.md

Provides examples for saving binary responses to files in a Node.js environment. It covers different methods of consuming the response body, including using `ReadableStream` for efficiency, `ArrayBuffer`, `Blob`, and `Uint8Array`.

```typescript
import { createWriteStream } from 'fs';
import { Readable } from 'stream';
import { pipeline } from 'stream/promises';

const response = await client.domains.getZoneFile(...);

const stream = response.stream();
const nodeStream = Readable.fromWeb(stream);
const writeStream = createWriteStream('path/to/file');

await pipeline(nodeStream, writeStream);
```

```typescript
import { writeFile } from 'fs/promises';

const response = await client.domains.getZoneFile(...);

const arrayBuffer = await response.arrayBuffer();
await writeFile('path/to/file', Buffer.from(arrayBuffer));
```

```typescript
import { writeFile } from 'fs/promises';

const response = await client.domains.getZoneFile(...);

const blob = await response.blob();
const arrayBuffer = await blob.arrayBuffer();
await writeFile('output.bin', Buffer.from(arrayBuffer));
```

```typescript
import { writeFile } from 'fs/promises';

const response = await client.domains.getZoneFile(...);

const bytes = await response.bytes();
await writeFile('path/to/file', bytes);
```

--------------------------------

### Get Domain Zone File using AgentMail Node.js

Source: https://context7.com/agentmail-to/agentmail-node/llms.txt

Downloads the DNS zone file for a specified domain. Requires an API key for authentication. Outputs the zone file content to 'zone.txt'.

```typescript
import { AgentMailClient } from "agentmail";
import { writeFile } from 'fs/promises';

const client = new AgentMailClient({ apiKey: "YOUR_API_KEY" });

const response = await client.domains.getZoneFile("domain_123");
const arrayBuffer = await response.arrayBuffer();

await writeFile('zone.txt', Buffer.from(arrayBuffer));
```

--------------------------------

### Add Custom Query Parameters to AgentMail Client Request (TypeScript)

Source: https://github.com/agentmail-to/agentmail-node/blob/main/README.md

This example illustrates how to append custom query string parameters to requests made using the AgentMail client. The `queryParams` option allows specifying key-value pairs that will be added to the URL's query string.

```typescript
const response = await client.inboxes.create(..., {
    queryParams: {
        'customQueryParamKey': 'custom query param value'
    }
});
```

--------------------------------

### AgentMail Metrics: List

Source: https://github.com/agentmail-to/agentmail-node/blob/main/reference.md

Retrieves a list of metrics. Requires start and end timestamps within the request object. Optionally accepts request options.

```typescript
await client.metrics.list({
    startTimestamp: new Date("2024-01-15T09:30:00.000Z"),
    endTimestamp: new Date("2024-01-15T09:30:00.000Z")
});
```

--------------------------------

### Get Domain Zone File - TypeScript

Source: https://github.com/agentmail-to/agentmail-node/blob/main/reference.md

Retrieves the zone file for a specified domain. Requires a domain ID and optional request options. Returns a binary response.

```typescript
await client.domains.getZoneFile("domain_id");
```

--------------------------------

### Configure Request Timeout for AgentMail Client (TypeScript)

Source: https://github.com/agentmail-to/agentmail-node/blob/main/README.md

This example demonstrates how to set a custom timeout duration for AgentMail client requests. The `timeoutInSeconds` option allows overriding the default 60-second timeout to a specified value, such as 30 seconds.

```typescript
const response = await client.inboxes.create(..., {
    timeoutInSeconds: 30 // override timeout to 30s
});
```

--------------------------------

### Get Inbox Metrics with Agentmail Node.js SDK

Source: https://context7.com/agentmail-to/agentmail-node/llms.txt

Retrieves metrics for a specified inbox within a given time range. Requires an API key for authentication and accepts start and end timestamps as input.

```typescript
import { AgentMailClient } from "agentmail";

const client = new AgentMailClient({ apiKey: "YOUR_API_KEY" });

const inboxMetrics = await client.inboxes.metrics.get("inbox_abc123", {
  startTimestamp: new Date("2024-01-01T00:00:00Z"),
  endTimestamp: new Date("2024-01-31T23:59:59Z")
});
```

--------------------------------

### Build the Project (Bash)

Source: https://github.com/agentmail-to/agentmail-node/blob/main/CONTRIBUTING.md

Compiles the project's code, typically generating distributable files. This command is essential after making code changes.

```bash
pnpm build
```

--------------------------------

### Get Organization Metrics using AgentMail Node.js

Source: https://context7.com/agentmail-to/agentmail-node/llms.txt

Retrieves email metrics for your organization within a specified time range. Requires an API key. Accepts start and end timestamps as Date objects.

```typescript
import { AgentMailClient } from "agentmail";

const client = new AgentMailClient({ apiKey: "YOUR_API_KEY" });

const metrics = await client.metrics.list({
  startTimestamp: new Date("2024-01-01T00:00:00Z"),
  endTimestamp: new Date("2024-01-31T23:59:59Z")
});

console.log(metrics);
// { sent: 1500, received: 2300, delivered: 1480, bounced: 20, ... }
```

--------------------------------

### Get Inbox Metrics using AgentMail Node.js SDK

Source: https://github.com/agentmail-to/agentmail-node/blob/main/reference.md

Retrieves metrics for a specific inbox. Requires an inbox ID and optionally accepts a request object with start and end timestamps. The response is of type AgentMail.ListMetricsResponse.

```typescript
await client.inboxes.metrics.get("inbox_id", {
    startTimestamp: new Date("2024-01-15T09:30:00.000Z"),
    endTimestamp: new Date("2024-01-15T09:30:00.000Z")
});
```

--------------------------------

### Save Binary Response to File in Bun

Source: https://github.com/agentmail-to/agentmail-node/blob/main/README.md

Illustrates how to save binary responses to files using Bun. It demonstrates saving directly from `ReadableStream`, `ArrayBuffer`, `Blob`, and `Uint8Array`.

```typescript
const response = await client.domains.getZoneFile(...);

const stream = response.stream();
await Bun.write('path/to/file', stream);
```

```typescript
const response = await client.domains.getZoneFile(...);

const arrayBuffer = await response.arrayBuffer();
await Bun.write('path/to/file', arrayBuffer);
```

```typescript
const response = await client.domains.getZoneFile(...);

const blob = await response.blob();
await Bun.write('path/to/file', blob);
```

```typescript
const response = await client.domains.getZoneFile(...);

const bytes = await response.bytes();
await Bun.write('path/to/file', bytes);
```

--------------------------------

### Initialize AgentMail Client (TypeScript)

Source: https://context7.com/agentmail-to/agentmail-node/llms.txt

Initializes the AgentMail client using your API key. This client instance is then used to access all SDK functionalities.

```typescript
import { AgentMailClient } from "agentmail";

const client = new AgentMailClient({
  apiKey: "YOUR_API_KEY"
});
```

--------------------------------

### Get Message Attachment

Source: https://context7.com/agentmail-to/agentmail-node/llms.txt

Download a specific attachment from a message.

```APIDOC
## GET /inboxes/{inboxId}/messages/{messageId}/attachments/{attachmentId}

### Description
Download a specific attachment from a message.

### Method
GET

### Endpoint
`/inboxes/{inboxId}/messages/{messageId}/attachments/{attachmentId}`

### Parameters
#### Path Parameters
- **inboxId** (string) - Required - The ID of the inbox.
- **messageId** (string) - Required - The ID of the message containing the attachment.
- **attachmentId** (string) - Required - The ID of the attachment to download.

### Response
#### Success Response (200)
- **id** (string) - The ID of the attachment.
- **filename** (string) - The name of the attachment file.
- **contentType** (string) - The MIME type of the attachment.
- **content** (string) - The base64 encoded content of the attachment.
- **size** (integer) - The size of the attachment in bytes.

#### Response Example
```json
{
  "id": "attachment_789",
  "filename": "report.pdf",
  "contentType": "application/pdf",
  "content": "base64_data...",
  "size": 12345
}
```
```

--------------------------------

### Customize Fetch Client in AgentMail Node.js SDK

Source: https://github.com/agentmail-to/agentmail-node/blob/main/README.md

Illustrates how to provide a custom fetch implementation to the AgentMail client, useful for unsupported environments.

```typescript
import { AgentMailClient } from "agentmail";

const client = new AgentMailClient({
    ...
    fetcher: // provide your implementation here
});
```

--------------------------------

### Get Raw Message

Source: https://context7.com/agentmail-to/agentmail-node/llms.txt

Retrieve the raw MIME content of a message.

```APIDOC
## GET /inboxes/{inboxId}/messages/{messageId}/raw

### Description
Retrieve the raw MIME content of a message.

### Method
GET

### Endpoint
`/inboxes/{inboxId}/messages/{messageId}/raw`

### Parameters
#### Path Parameters
- **inboxId** (string) - Required - The ID of the inbox.
- **messageId** (string) - Required - The ID of the message to retrieve.

### Response
#### Success Response (200)
- **arrayBuffer** - An ArrayBuffer containing the raw MIME content of the message.

#### Response Example
(Response is binary data, typically saved to a file like `message.eml`)
```

--------------------------------

### Inboxes Metrics

Source: https://github.com/agentmail-to/agentmail-node/blob/main/reference.md

Retrieves metrics for a specific inbox. Supports filtering by start and end timestamps.

```APIDOC
## GET /inboxes/{inbox_id}/metrics

### Description
Retrieves metrics for a specific inbox.

### Method
GET

### Endpoint
`/inboxes/{inbox_id}/metrics`

### Parameters
#### Path Parameters
- **inbox_id** (AgentMail.InboxId) - Required - The ID of the inbox.

#### Query Parameters
- **startTimestamp** (Date) - Optional - The start of the time range for metrics.
- **endTimestamp** (Date) - Optional - The end of the time range for metrics.

#### Request Body
None

### Request Example
```typescript
await client.inboxes.metrics.get("inbox_id", {
    startTimestamp: new Date("2024-01-15T09:30:00.000Z"),
    endTimestamp: new Date("2024-01-15T09:30:00.000Z")
});
```

### Response
#### Success Response (200)
- **ListMetricsResponse** (AgentMail.ListMetricsResponse) - The response containing inbox metrics.

#### Response Example
```json
{
  "example": "response body"
}
```
```

--------------------------------

### GET /inboxes/{inbox_id}/messages/{message_id}/raw

Source: https://github.com/agentmail-to/agentmail-node/blob/main/reference.md

Retrieves the raw content of a message within an inbox.

```APIDOC
## GET /inboxes/{inbox_id}/messages/{message_id}/raw

### Description
Retrieves the raw content of a message within an inbox.

### Method
GET

### Endpoint
/inboxes/{inbox_id}/messages/{message_id}/raw

### Parameters
#### Path Parameters
- **inbox_id** (AgentMail.InboxId) - Required - The ID of the inbox.
- **message_id** (AgentMail.MessageId) - Required - The ID of the message.

#### Query Parameters
- **requestOptions** (MessagesClient.RequestOptions) - Optional - Additional request options.

### Request Example
```typescript
await client.inboxes.messages.getRaw("inbox_id", "message_id");
```

### Response
#### Success Response (200)
- **core.BinaryResponse** - The raw binary content of the message.
```

--------------------------------

### Configure Custom Headers and Query Parameters with Agentmail Node.js SDK

Source: https://context7.com/agentmail-to/agentmail-node/llms.txt

Shows how to add custom headers to the client instance and per-request headers and query parameters. This allows for enhanced request customization.

```typescript
import { AgentMailClient } from "agentmail";

const client = new AgentMailClient({
  apiKey: "YOUR_API_KEY",
  headers: {
    'X-Custom-Header': 'custom-value'
  }
});

const inbox = await client.inboxes.get("inbox_abc123", {
  headers: { 'X-Request-Id': 'req_123' },
  queryParams: { include: 'stats' }
});
```

--------------------------------

### Get Message - TypeScript

Source: https://github.com/agentmail-to/agentmail-node/blob/main/reference.md

Retrieves a specific email message. Requires inbox ID and message ID.

```typescript
await client.inboxes.messages.get("inbox_id", "message_id");
```

--------------------------------

### Lists API

Source: https://github.com/agentmail-to/agentmail-node/blob/main/reference.md

Endpoints for managing AgentMail lists, including getting, creating, updating, and deleting list entries.

```APIDOC
## DELETE /lists/delete

### Description
Deletes an entry from an AgentMail list.

### Method
DELETE

### Endpoint
/lists/delete

### Parameters
#### Query Parameters
- **direction** (AgentMail.Direction) - Required - The direction of the list.
- **type** (AgentMail.ListType) - Required - The type of the list.
- **entry** (string) - Required - The email address or domain to delete.
- **requestOptions** (ListsClient.RequestOptions) - Optional - Options for the request.

### Request Example
```typescript
await client.lists.delete("send", "allow", "entry");
```

### Response
#### Success Response (200)
- **void** - Indicates successful deletion.

#### Response Example
```json
{
  "message": "Entry deleted successfully"
}
```
```

--------------------------------

### Custom Pino Logger for AgentMail SDK

Source: https://github.com/agentmail-to/agentmail-node/blob/main/README.md

Shows how to integrate the Pino logging library with the AgentMail SDK by implementing the ILogger interface.

```typescript
import pino from 'pino';
import { logging } from "agentmail";

const pinoLogger = pino({...});

const logger: logging.ILogger = {
  debug: (msg, ...args) => pinoLogger.debug(args, msg),
  info: (msg, ...args) => pinoLogger.info(args, msg),
  warn: (msg, ...args) => pinoLogger.warn(args, msg),
  error: (msg, ...args) => pinoLogger.error(args, msg),
};
```

--------------------------------

### GET /inboxes/{inbox_id}/messages/{message_id}/attachments/{attachment_id}

Source: https://github.com/agentmail-to/agentmail-node/blob/main/reference.md

Retrieves a specific attachment from a message within an inbox.

```APIDOC
## GET /inboxes/{inbox_id}/messages/{message_id}/attachments/{attachment_id}

### Description
Retrieves a specific attachment from a message within an inbox.

### Method
GET

### Endpoint
/inboxes/{inbox_id}/messages/{message_id}/attachments/{attachment_id}

### Parameters
#### Path Parameters
- **inbox_id** (AgentMail.InboxId) - Required - The ID of the inbox.
- **message_id** (AgentMail.MessageId) - Required - The ID of the message.
- **attachment_id** (AgentMail.AttachmentId) - Required - The ID of the attachment.

#### Query Parameters
- **requestOptions** (MessagesClient.RequestOptions) - Optional - Additional request options.

### Request Example
```typescript
await client.inboxes.messages.getAttachment("inbox_id", "message_id", "attachment_id");
```

### Response
#### Success Response (200)
- **AgentMail.AttachmentResponse** - The response containing the attachment details.
```

--------------------------------

### Get Inbox Details (TypeScript)

Source: https://context7.com/agentmail-to/agentmail-node/llms.txt

Retrieves detailed information about a specific email inbox using its unique ID.

```typescript
import { AgentMailClient } from "agentmail";

const client = new AgentMailClient({ apiKey: "YOUR_API_KEY" });

const inbox = await client.inboxes.get("inbox_abc123");

console.log(inbox.email);
// "support@agentmail.to"
```

--------------------------------

### Run Test Suite (Bash)

Source: https://github.com/agentmail-to/agentmail-node/blob/main/CONTRIBUTING.md

Executes the project's comprehensive test suite to ensure code integrity. This includes unit, integration, and wire tests.

```bash
pnpm test
```

--------------------------------

### AgentMail Organizations: Get

Source: https://github.com/agentmail-to/agentmail-node/blob/main/reference.md

Retrieves information about the current organization. This operation is straightforward and may optionally accept request options.

```typescript
await client.organizations.get();
```

--------------------------------

### Download Binary Response as Blob (JavaScript)

Source: https://github.com/agentmail-to/agentmail-node/blob/main/README.md

This snippet demonstrates how to read a ReadableStream from a response, collect its chunks, create a Blob from these chunks, and trigger a file download. It utilizes the browser's Blob and URL APIs for creating downloadable content.

```javascript
const { done, value } = await reader.read();
  if (done) break;
  chunks.push(value);
}

const blob = new Blob(chunks);
const url = URL.createObjectURL(blob);

// trigger download
const a = document.createElement('a');
a.href = url;
a.download = 'filename';
a.click();
URL.revokeObjectURL(url);
```

--------------------------------

### Get Message Details (TypeScript)

Source: https://context7.com/agentmail-to/agentmail-node/llms.txt

Retrieves the full details of a specific email message using both the inbox ID and message ID.

```typescript
import { AgentMailClient } from "agentmail";

const client = new AgentMailClient({ apiKey: "YOUR_API_KEY" });

const message = await client.inboxes.messages.get("inbox_abc123", "msg_456");

console.log(message);
// { id: "msg_456", subject: "Re: Hello", from: "user@example.com", to: ["support@agentmail.to"], text: "...", html: "...", attachments: [...] }
```

--------------------------------

### Get Draft - TypeScript

Source: https://github.com/agentmail-to/agentmail-node/blob/main/reference.md

Retrieves a specific draft by its ID. Requires the draft ID and optional request options. Returns the draft object.

```typescript
await client.drafts.get("draft_id");
```

--------------------------------

### Create a Pod List Entry (TypeScript)

Source: https://github.com/agentmail-to/agentmail-node/blob/main/reference.md

Creates a new entry in a pod's list, specifying direction and type. Requires pod ID, direction, type, and entry details.

```typescript
await client.pods.lists.create("pod_id", "send", "allow", {
    entry: "entry"
});
```

--------------------------------

### AgentMail Pod Lists API

Source: https://github.com/agentmail-to/agentmail-node/blob/main/reference.md

Manage lists within AgentMail pods, including listing entries, getting specific entries, and deleting entries.

```APIDOC
## POST /pods/lists/list

### Description
Retrieves a list of entries from a specified pod list.

### Method
POST

### Endpoint
/pods/lists/list

### Parameters
#### Path Parameters
- **pod_id** (AgentMail.PodId) - Required - The ID of the pod.
- **direction** (AgentMail.Direction) - Required - The direction of the list.
- **type** (AgentMail.ListType) - Required - The type of the list.

#### Query Parameters
- **request** (AgentMail.CreateListEntryRequest) - Optional - Request object for creating a list entry.
- **requestOptions** (ListsClient.RequestOptions) - Optional - Options for the request.

### Request Example
```json
{
  "pod_id": "example_pod_id",
  "direction": "send",
  "type": "allow",
  "request": {},
  "requestOptions": {}
}
```

### Response
#### Success Response (200)
- **entries** (Array<AgentMail.PodListEntry>) - A list of entries in the pod list.

#### Response Example
```json
{
  "entries": [
    {
      "value": "example@example.com",
      "comment": "Example entry"
    }
  ]
}
```

## GET /pods/lists/get

### Description
Retrieves a specific entry from a pod list.

### Method
GET

### Endpoint
/pods/lists/get

### Parameters
#### Path Parameters
- **pod_id** (AgentMail.PodId) - Required - The ID of the pod.
- **direction** (AgentMail.Direction) - Required - The direction of the list.
- **type** (AgentMail.ListType) - Required - The type of the list.
- **entry** (string) - Required - The email address or domain of the entry to retrieve.

#### Query Parameters
- **requestOptions** (ListsClient.RequestOptions) - Optional - Options for the request.

### Request Example
```json
{
  "pod_id": "example_pod_id",
  "direction": "send",
  "type": "allow",
  "entry": "example@example.com"
}
```

### Response
#### Success Response (200)
- **entry** (AgentMail.PodListEntry) - The requested list entry.

#### Response Example
```json
{
  "value": "example@example.com",
  "comment": "Example entry"
}
```

## DELETE /pods/lists/delete

### Description
Deletes a specific entry from a pod list.

### Method
DELETE

### Endpoint
/pods/lists/delete

### Parameters
#### Path Parameters
- **pod_id** (AgentMail.PodId) - Required - The ID of the pod.
- **direction** (AgentMail.Direction) - Required - The direction of the list.
- **type** (AgentMail.ListType) - Required - The type of the list.
- **entry** (string) - Required - The email address or domain of the entry to delete.

#### Query Parameters
- **requestOptions** (ListsClient.RequestOptions) - Optional - Options for the request.

### Request Example
```json
{
  "pod_id": "example_pod_id",
  "direction": "send",
  "type": "allow",
  "entry": "example@example.com"
}
```

### Response
#### Success Response (200)
- **void** - Indicates successful deletion.

#### Response Example
```json
{}
```
```

--------------------------------

### Get a Specific Inbox (TypeScript)

Source: https://github.com/agentmail-to/agentmail-node/blob/main/reference.md

Fetches a specific inbox by its ID from a pod. Requires pod ID and inbox ID, and can include request options.

```typescript
await client.pods.inboxes.get("pod_id", "inbox_id");
```

--------------------------------

### Create Pod using AgentMail Node.js

Source: https://context7.com/agentmail-to/agentmail-node/llms.txt

Creates a new pod for organizing inboxes and resources within a multi-tenant environment. Requires an API key. Accepts a name and client ID for the pod.

```typescript
import { AgentMailClient } from "agentmail";

const client = new AgentMailClient({ apiKey: "YOUR_API_KEY" });

const pod = await client.pods.create({
  name: "Customer Tenant A",
  clientId: "tenant_a_ref"
});

console.log(pod);
// { id: "pod_123", name: "Customer Tenant A", createdAt: "2024-01-15T09:30:00Z" }
```

--------------------------------

### Trigger File Download in Browser from Binary Response

Source: https://github.com/agentmail-to/agentmail-node/blob/main/README.md

Demonstrates how to trigger a file download in a web browser using binary data obtained from an Agentmail API response. It primarily uses the `Blob` object and `URL.createObjectURL` for efficient handling.

```typescript
const response = await client.domains.getZoneFile(...);

const blob = await response.blob();
const url = URL.createObjectURL(blob);

// trigger download
const a = document.createElement('a');
a.href = url;
a.download = 'filename';
a.click();
URL.revokeObjectURL(url);
```

```typescript
const response = await client.domains.getZoneFile(...);

const stream = response.stream();
const reader = stream.getReader();
const chunks = [];

while (true) {

```

--------------------------------

### Create Webhook - TypeScript

Source: https://context7.com/agentmail-to/agentmail-node/llms.txt

Sets up a webhook to receive real-time notifications for various email events. Requires a URL for the webhook endpoint and a list of event types to subscribe to. Optionally accepts inbox and pod IDs to filter events. Returns the created webhook configuration.

```typescript
import { AgentMailClient } from "agentmail";

const client = new AgentMailClient({ apiKey: "YOUR_API_KEY" });

const webhook = await client.webhooks.create({
  url: "https://your-server.com/webhook",
  eventTypes: [
    "message.received",
    "message.sent",
    "message.delivered",
    "message.bounced",
    "message.complained",
    "message.rejected",
    "domain.verified"
  ],
  inboxIds: ["inbox_abc123", "inbox_def456"],
  podIds: ["pod_123"]
});

console.log(webhook);
// { id: "webhook_123", url: "https://your-server.com/webhook", eventTypes: [...], secret: "whsec_..." }
```

--------------------------------

### AgentMail Pod Threads API

Source: https://github.com/agentmail-to/agentmail-node/blob/main/reference.md

Manage threads within AgentMail pods, including listing threads, retrieving a specific thread, and getting thread attachments.

```APIDOC
## POST /pods/threads/list

### Description
Retrieves a list of threads from a specified pod.

### Method
POST

### Endpoint
/pods/threads/list

### Parameters
#### Path Parameters
- **pod_id** (AgentMail.PodId) - Required - The ID of the pod.

#### Query Parameters
- **request** (AgentMail.pods.ListThreadsRequest) - Optional - Request object for listing threads.
- **requestOptions** (ThreadsClient.RequestOptions) - Optional - Options for the request.

### Request Example
```json
{
  "pod_id": "example_pod_id"
}
```

### Response
#### Success Response (200)
- **threads** (Array<AgentMail.Thread>) - A list of threads in the pod.

#### Response Example
```json
{
  "threads": [
    {
      "id": "thread_123",
      "subject": "Example Subject"
    }
  ]
}
```

## GET /pods/threads/get

### Description
Retrieves a specific thread from a pod.

### Method
GET

### Endpoint
/pods/threads/get

### Parameters
#### Path Parameters
- **pod_id** (AgentMail.PodId) - Required - The ID of the pod.
- **thread_id** (AgentMail.ThreadId) - Required - The ID of the thread.

#### Query Parameters
- **requestOptions** (ThreadsClient.RequestOptions) - Optional - Options for the request.

### Request Example
```json
{
  "pod_id": "example_pod_id",
  "thread_id": "thread_123"
}
```

### Response
#### Success Response (200)
- **thread** (AgentMail.Thread) - The requested thread object.

#### Response Example
```json
{
  "id": "thread_123",
  "subject": "Example Subject"
}
```

## GET /pods/threads/getAttachment

### Description
Retrieves an attachment from a specific thread within a pod.

### Method
GET

### Endpoint
/pods/threads/getAttachment

### Parameters
#### Path Parameters
- **pod_id** (AgentMail.PodId) - Required - The ID of the pod.
- **thread_id** (AgentMail.ThreadId) - Required - The ID of the thread.
- **attachment_id** (AgentMail.AttachmentId) - Required - The ID of the attachment.

#### Query Parameters
- **requestOptions** (ThreadsClient.RequestOptions) - Optional - Options for the request.

### Request Example
```json
{
  "pod_id": "example_pod_id",
  "thread_id": "thread_123",
  "attachment_id": "attachment_abc"
}
```

### Response
#### Success Response (200)
- **attachment** (AgentMail.AttachmentResponse) - The requested attachment object.

#### Response Example
```json
{
  "filename": "example.txt",
  "contentType": "text/plain",
  "content": "SGVsbG8gV29ybGQ="
}
```
```

--------------------------------

### List Pods using AgentMail Node.js

Source: https://context7.com/agentmail-to/agentmail-node/llms.txt

Retrieves a list of all pods within an organization. Requires an API key for authentication. Returns an array of pod objects.

```typescript
import { AgentMailClient } from "agentmail";

const client = new AgentMailClient({ apiKey: "YOUR_API_KEY" });

const response = await client.pods.list();

console.log(response.pods);
// [{ id: "pod_123", name: "Customer Tenant A", ... ]
```

--------------------------------

### List API Keys using AgentMail Node.js

Source: https://context7.com/agentmail-to/agentmail-node/llms.txt

Retrieves a list of all API keys associated with your organization. Requires an API key for authentication. Only displays the name, prefix, and creation date, not the full keys.

```typescript
import { AgentMailClient } from "agentmail";

const client = new AgentMailClient({ apiKey: "YOUR_API_KEY" });

const response = await client.apiKeys.list();

console.log(response.apiKeys);
// [{ name: "Production Server Key", prefix: "am_live_", createdAt: "..." ]
```

--------------------------------

### Get a Specific Draft (TypeScript)

Source: https://github.com/agentmail-to/agentmail-node/blob/main/reference.md

Retrieves a specific draft by its ID from a given pod. Requires pod ID and draft ID, and can include request options.

```typescript
await client.pods.drafts.get("pod_id", "draft_id");
```

--------------------------------

### Get a specific Domain by ID using AgentMail Node.js Client

Source: https://github.com/agentmail-to/agentmail-node/blob/main/reference.md

Retrieves details for a specific domain using its ID. Accepts domain_id and optional requestOptions.

```typescript
await client.domains.get("domain_id");
```

--------------------------------

### Get a specific Webhook by ID using AgentMail Node.js Client

Source: https://github.com/agentmail-to/agentmail-node/blob/main/reference.md

Retrieves details for a specific webhook using its ID. Accepts webhook_id and optional requestOptions.

```typescript
await client.webhooks.get("webhook_id");
```

--------------------------------

### Run Specific Test Types (Bash)

Source: https://github.com/agentmail-to/agentmail-node/blob/main/CONTRIBUTING.md

Allows running specific categories of tests, such as unit tests or wire/integration tests. Useful for targeted debugging.

```bash
pnpm test:unit
```

```bash
pnpm test:wire
```

--------------------------------

### Create Domain - TypeScript

Source: https://github.com/agentmail-to/agentmail-node/blob/main/reference.md

Creates a new domain. Requires a request object containing domain details and feedback enablement, along with optional request options. Returns the created domain object.

```typescript
await client.domains.create({
    domain: "domain",
    feedbackEnabled: true
});
```

--------------------------------

### Get Organization Details with Agentmail Node.js SDK

Source: https://context7.com/agentmail-to/agentmail-node/llms.txt

Retrieves details about the current organization associated with the API key. This function does not require any specific input parameters.

```typescript
import { AgentMailClient } from "agentmail";

const client = new AgentMailClient({ apiKey: "YOUR_API_KEY" });

const org = await client.organizations.get();

console.log(org);
// { id: "org_123", name: "My Company", createdAt: "..." }
```

--------------------------------

### List Webhooks using AgentMail Node.js Client

Source: https://github.com/agentmail-to/agentmail-node/blob/main/reference.md

Lists all configured webhooks. Requires AgentMail.webhooks.ListWebhooksRequest and WebhooksClient.RequestOptions.

```typescript
await client.webhooks.list(request, requestOptions);
```

--------------------------------

### Get Draft Attachment (TypeScript)

Source: https://github.com/agentmail-to/agentmail-node/blob/main/reference.md

Fetches an attachment for a specific draft. Requires pod ID, draft ID, and attachment ID, along with optional request options.

```typescript
await client.pods.drafts.getAttachment("pod_id", "draft_id", "attachment_id");
```

--------------------------------

### AgentMail Lists: Get Entry

Source: https://github.com/agentmail-to/agentmail-node/blob/main/reference.md

Retrieves a specific entry from a list. Requires direction, type, and the entry identifier. Optionally accepts request options for advanced configuration.

```typescript
await client.lists.get("send", "allow", "entry");
```

--------------------------------

### Get Raw Message Content - TypeScript

Source: https://github.com/agentmail-to/agentmail-node/blob/main/reference.md

Fetches the raw content of a message from an inbox. Requires inbox ID and message ID. Request options can also be provided.

```typescript
await client.inboxes.messages.getRaw("inbox_id", "message_id");
```

--------------------------------

### Create a List Entry using AgentMail Node.js SDK

Source: https://github.com/agentmail-to/agentmail-node/blob/main/reference.md

Creates a new entry in a specified list. Requires direction, type, and a request object containing the entry details. Request options can also be provided. The response is of type AgentMail.ListEntry.

```typescript
await client.lists.create("send", "allow", {
    entry: "entry"
});
```

--------------------------------

### Get Draft Attachment - TypeScript

Source: https://github.com/agentmail-to/agentmail-node/blob/main/reference.md

Retrieves an attachment from a specific draft. Requires the draft ID, attachment ID, and optional request options. Returns the attachment response.

```typescript
await client.drafts.getAttachment("draft_id", "attachment_id");
```

--------------------------------

### Check Code Style (Bash)

Source: https://github.com/agentmail-to/agentmail-node/blob/main/CONTRIBUTING.md

Verifies that the codebase adheres to the project's linting and formatting rules. This command checks for style violations without making changes.

```bash
pnpm run lint
```

```bash
pnpm run format:check
```

--------------------------------

### List Webhooks - TypeScript

Source: https://context7.com/agentmail-to/agentmail-node/llms.txt

Retrieves a list of all currently configured webhooks. This function does not require any parameters and returns an object containing an array of webhook configurations.

```typescript
import { AgentMailClient } from "agentmail";

const client = new AgentMailClient({ apiKey: "YOUR_API_KEY" });

const response = await client.webhooks.list();

console.log(response.webhooks);
// [{ id: "webhook_123", url: "https://...", eventTypes: [...], ... }]
```

--------------------------------

### Get Attachment from Draft - TypeScript

Source: https://github.com/agentmail-to/agentmail-node/blob/main/reference.md

Retrieves a specific attachment from an email draft. Requires inbox ID, draft ID, and attachment ID. Optionally accepts request options.

```typescript
await client.inboxes.drafts.getAttachment("inbox_id", "draft_id", "attachment_id");
```

--------------------------------

### Configure Logging with Agentmail Node.js SDK

Source: https://context7.com/agentmail-to/agentmail-node/llms.txt

Shows how to enable and configure SDK logging for debugging purposes. This includes setting the log level, specifying a logger implementation, and controlling silent mode.

```typescript
import { AgentMailClient, logging } from "agentmail";

const client = new AgentMailClient({
  apiKey: "YOUR_API_KEY",
  logging: {
    level: logging.LogLevel.Debug,
    logger: new logging.ConsoleLogger(),
    silent: false
  }
});
```

--------------------------------

### Get Inbox Draft - TypeScript

Source: https://github.com/agentmail-to/agentmail-node/blob/main/reference.md

Retrieves a specific draft from an inbox by its IDs. Requires the inbox ID, draft ID, and optional request options. Returns the draft object.

```typescript
await client.inboxes.drafts.get("inbox_id", "draft_id");
```

--------------------------------

### Configure Retries and Timeouts with Agentmail Node.js SDK

Source: https://context7.com/agentmail-to/agentmail-node/llms.txt

Illustrates how to configure automatic request retries and set a timeout for requests. This helps in managing network instability and ensuring timely responses.

```typescript
import { AgentMailClient } from "agentmail";

const client = new AgentMailClient({ apiKey: "YOUR_API_KEY" });

const inbox = await client.inboxes.get("inbox_abc123", {
  maxRetries: 3,
  timeoutInSeconds: 30
});
```

--------------------------------

### Download Binary Response as Blob (TypeScript)

Source: https://github.com/agentmail-to/agentmail-node/blob/main/README.md

This code converts an ArrayBuffer obtained from a response into a Blob, then creates a URL for this Blob to initiate a file download. It's useful for handling binary data responses that are received as ArrayBuffers.

```typescript
const response = await client.domains.getZoneFile(...);

const arrayBuffer = await response.arrayBuffer();
const blob = new Blob([arrayBuffer]);
const url = URL.createObjectURL(blob);

// trigger download
const a = document.createElement('a');
a.href = url;
a.download = 'filename';
a.click();
URL.revokeObjectURL(url);
```

--------------------------------

### Get Thread by ID - TypeScript

Source: https://context7.com/agentmail-to/agentmail-node/llms.txt

Retrieves a specific email thread, including all its messages, participants, and metadata. Requires an inbox ID and a thread ID. Returns a thread object.

```typescript
import { AgentMailClient } from "agentmail";

const client = new AgentMailClient({ apiKey: "YOUR_API_KEY" });

const thread = await client.inboxes.threads.get("inbox_abc123", "thread_123");

console.log(thread);
// { id: "thread_123", subject: "Project Discussion", messages: [...], participants: [...] }
```

--------------------------------

### Get Message Attachment using AgentMail Node.js

Source: https://context7.com/agentmail-to/agentmail-node/llms.txt

Downloads a specific attachment from a message. Requires inbox ID, message ID, and attachment ID. Returns attachment metadata and content.

```typescript
import { AgentMailClient } from "agentmail";

const client = new AgentMailClient({ apiKey: "YOUR_API_KEY" });

const attachment = await client.inboxes.messages.getAttachment(
  "inbox_abc123",
  "msg_456",
  "attachment_789"
);

console.log(attachment);
// { id: "attachment_789", filename: "report.pdf", contentType: "application/pdf", content: "base64_data...", size: 12345 }
```

--------------------------------

### Lists API (Allow/Block Lists)

Source: https://context7.com/agentmail-to/agentmail-node/llms.txt

Endpoints for managing allow and block lists for email send/receive directions.

```APIDOC
## POST /lists/{direction}/{type}

### Description
Add an email or domain to allow or block lists for send/receive directions.

### Method
POST

### Endpoint
`/lists/{direction}/{type}`

### Parameters
#### Path Parameters
- **direction** (string) - Required - The direction of the list ('send' or 'receive').
- **type** (string) - Required - The type of list ('allow' or 'block').

#### Request Body
- **entry** (string) - Required - The email address or domain to add to the list.

### Request Example
```json
// Block a domain from sending
{
  "entry": "spam-domain.com"
}

// Allow a specific email for receiving
{
  "entry": "trusted@partner.com"
}
```

### Response
#### Success Response (201)
- **entry** (string) - The added email address or domain.
- **direction** (string) - The direction of the list ('send' or 'receive').
- **type** (string) - The type of list ('allow' or 'block').
- **createdAt** (string) - The timestamp when the entry was created.

#### Response Example
```json
{
  "entry": "spam-domain.com",
  "direction": "send",
  "type": "block",
  "createdAt": "2024-01-18T14:00:00Z"
}
```

## GET /lists/{direction}/{type}

### Description
Retrieve entries from a specific list.

### Method
GET

### Endpoint
`/lists/{direction}/{type}`

### Parameters
#### Path Parameters
- **direction** (string) - Required - The direction of the list ('send' or 'receive').
- **type** (string) - Required - The type of list ('allow' or 'block').

### Response
#### Success Response (200)
- **entries** (array) - An array of list entry objects.
  - **entry** (string) - The email address or domain.
  - **direction** (string) - The direction of the list.
  - **type** (string) - The type of list.
  - **createdAt** (string) - The timestamp when the entry was created.

#### Response Example
```json
{
  "entries": [
    { "entry": "spam-domain.com", "direction": "send", "type": "block", "createdAt": "2024-01-18T14:00:00Z" },
    { "entry": "another-spam.net", "direction": "send", "type": "block", "createdAt": "2024-01-19T09:00:00Z" }
  ]
}
```

## DELETE /lists/{direction}/{type}/{entry}

### Description
Remove an entry from a list.

### Method
DELETE

### Endpoint
`/lists/{direction}/{type}/{entry}`

### Parameters
#### Path Parameters
- **direction** (string) - Required - The direction of the list ('send' or 'receive').
- **type** (string) - Required - The type of list ('allow' or 'block').
- **entry** (string) - Required - The email address or domain to remove.

### Response
#### Success Response (204)
No content.

#### Response Example
(No response body)
```

--------------------------------

### Create API Key using AgentMail Node.js

Source: https://context7.com/agentmail-to/agentmail-node/llms.txt

Generates a new API key for your organization. Requires an existing API key for authentication. The full API key is only displayed upon creation.

```typescript
import { AgentMailClient } from "agentmail";

const client = new AgentMailClient({ apiKey: "YOUR_API_KEY" });

const newKey = await client.apiKeys.create({
  name: "Production Server Key"
});

console.log(newKey);
// { apiKey: "am_live_xxxxx", name: "Production Server Key", prefix: "am_live_", createdAt: "..." }
// Note: The full API key is only shown once upon creation
```

--------------------------------

### Get Attachment from Inbox Message - TypeScript

Source: https://github.com/agentmail-to/agentmail-node/blob/main/reference.md

Retrieves a specific attachment from a message within an inbox. Requires inbox ID, message ID, and attachment ID. Optionally accepts request options.

```typescript
await client.inboxes.messages.getAttachment("inbox_id", "message_id", "attachment_id");
```

--------------------------------

### Run Combined Check and Fix (Bash)

Source: https://github.com/agentmail-to/agentmail-node/blob/main/CONTRIBUTING.md

Executes both linting and formatting checks and automatically fixes any identified issues. This is a convenient command to ensure code quality.

```bash
pnpm run check:fix
```

--------------------------------

### Create Pod using AgentMail Node.js Client

Source: https://github.com/agentmail-to/agentmail-node/blob/main/reference.md

Creates a new pod with the AgentMail Node.js client. The creation can be configured with parameters defined in `AgentMail.CreatePodRequest`. Optional request options are also supported.

```typescript
await client.pods.create({});
```

--------------------------------

### Get Attachment from AgentMail Pod Thread (Node.js)

Source: https://github.com/agentmail-to/agentmail-node/blob/main/reference.md

Retrieves an attachment from a specific thread in an AgentMail pod. Requires pod ID, thread ID, and attachment ID. `requestOptions` can be used to modify request behavior.

```typescript
await client.pods.threads.getAttachment("pod_id", "thread_id", "attachment_id");
```

--------------------------------

### API Keys API

Source: https://context7.com/agentmail-to/agentmail-node/llms.txt

Endpoints for generating, listing, and deleting API keys.

```APIDOC
## POST /api-keys

### Description
Generate a new API key for your organization.

### Method
POST

### Endpoint
`/api-keys`

### Parameters
#### Request Body
- **name** (string) - Required - A descriptive name for the API key.

### Request Example
```json
{
  "name": "Production Server Key"
}
```

### Response
#### Success Response (201)
- **apiKey** (string) - The newly generated API key. This is only shown once upon creation.
- **name** (string) - The name of the API key.
- **prefix** (string) - The prefix of the API key.
- **createdAt** (string) - The timestamp when the API key was created.

#### Response Example
```json
{
  "apiKey": "am_live_xxxxx",
  "name": "Production Server Key",
  "prefix": "am_live_",
  "createdAt": "2024-01-20T10:00:00Z"
}
```

## GET /api-keys

### Description
Retrieve all API keys (shows prefix only, not full keys).

### Method
GET

### Endpoint
`/api-keys`

### Response
#### Success Response (200)
- **apiKeys** (array) - An array of API key objects.
  - **name** (string) - The name of the API key.
  - **prefix** (string) - The prefix of the API key.
  - **createdAt** (string) - The timestamp when the API key was created.

#### Response Example
```json
{
  "apiKeys": [
    { "name": "Production Server Key", "prefix": "am_live_", "createdAt": "2024-01-20T10:00:00Z" },
    { "name": "Staging Key", "prefix": "am_test_", "createdAt": "2024-01-21T11:00:00Z" }
  ]
}
```

## DELETE /api-keys/{keyId}

### Description
Revoke an API key.

### Method
DELETE

### Endpoint
`/api-keys/{keyId}`

### Parameters
#### Path Parameters
- **keyId** (string) - Required - The ID of the API key to revoke.

### Response
#### Success Response (204)
No content.

#### Response Example
(No response body)
```

--------------------------------

### Get Specific Thread from AgentMail Pod (Node.js)

Source: https://github.com/agentmail-to/agentmail-node/blob/main/reference.md

Fetches details of a specific thread within an AgentMail pod using its ID. Requires the pod ID and thread ID. `requestOptions` can be provided for customizing the request.

```typescript
await client.pods.threads.get("pod_id", "thread_id");
```

--------------------------------

### Configure Logging in AgentMail Node.js SDK

Source: https://github.com/agentmail-to/agentmail-node/blob/main/README.md

Demonstrates how to configure the logging level, logger implementation, and silent mode for the AgentMail client. Supports custom loggers implementing the ILogger interface.

```typescript
import { AgentMailClient, logging } from "agentmail";

const client = new AgentMailClient({
    ...
    logging: {
        level: logging.LogLevel.Debug, // defaults to logging.LogLevel.Info
        logger: new logging.ConsoleLogger(), // defaults to ConsoleLogger
        silent: false, // defaults to true, set to false to enable logging
    }
});
```