Mailtrap Node.js Client

https://github.com/mailtrap/mailtrap-nodejs
Admin
The official Mailtrap Node.js client provides an SDK to seamlessly integrate Mailtrap's email...
Tokens:97,466
Snippets:529
Trust Score:8.2
License:MIT
Update:3 weeks ago
Show doc for...
Tokens:
Raw
### Fetch stats, email logs, and log details with MailtrapClient

Source: https://github.com/mailtrap/mailtrap-nodejs/blob/main/_autodocs/api-reference/email-logs-stats-api.md

Initializes MailtrapClient with a token and account ID, then shows how to get aggregated stats for a date range, grouped stats by domain, email logs with deep-object filters, and details for a specific message. The example logs delivery/bounce rates, total count, next page cursor, and event details.

```ts
const client = new MailtrapClient({ token, accountId: 12345 });

// Aggregated stats for a date range
const stats = await client.stats.get({
  start_date: "2024-01-01",
  end_date: "2024-01-31",
});
console.log(stats.delivery_rate, stats.bounce_rate);

// Grouped by domain / category / ESP / date
const byDomain = await client.stats.byDomain({
  start_date: "2024-01-01",
  end_date: "2024-01-31",
});

// Email logs with filters (deep-object query)
const logs = await client.emailLogs.getList({
  search_after: "<cursor-from-previous-response>",
  filters: {
    status: { operator: "equal", value: "delivered" },
    to: { operator: "ci_equal", value: "user@example.com" },
    events: { operator: "include_event", value: ["open", "click"] },
  },
});
console.log(logs.total_count, logs.next_page_cursor);

const details = await client.emailLogs.get(logs.messages[0].message_id);
if (details.events) {
  for (const event of details.events) {
    console.log(event.event_type, event.created_at);
  }
}
```

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

### Get all accounts usage example

Source: https://github.com/mailtrap/mailtrap-nodejs/blob/main/_autodocs/api-reference/general-api.md

Example of calling getAllAccounts() on the client's general.accounts property. The method returns a promise resolving to an array of User objects.

```typescript
const accounts = await client.general.accounts.getAllAccounts();
```

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

### Install mailtrap package

Source: https://github.com/mailtrap/mailtrap-nodejs/blob/main/README.md

Install the Mailtrap Node.js SDK using npm or Yarn.

```bash
npm install mailtrap

# or, if you are using Yarn:
yarn add mailtrap
```

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

### Query string serialization example

Source: https://github.com/mailtrap/mailtrap-nodejs/blob/main/_autodocs/api-reference/email-logs-stats-api.md

Example of the query string format produced by serializeEmailLogsParams using qs with arrayFormat: "brackets" and encodeValuesOnly: true. This Rails-style bracket notation is used for search_after and the deep filters object.

```text
filters[sent_after]=...&filters[to][operator]=ci_equal&filters[category][value][]=foo
```

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

### Install @types/nodemailer devDependency

Source: https://github.com/mailtrap/mailtrap-nodejs/blob/main/README.md

Install TypeScript type definitions for Nodemailer as a devDependency when using TypeScript.

```sh
npm install -D @types/nodemailer

# or, if you are using Yarn:
yarn add --dev @types/nodemailer
```

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

### GET /api/email-logs

Source: https://github.com/mailtrap/mailtrap-nodejs/blob/main/_autodocs/types/types-email-logs.md

Example of retrieving email logs with filters and pagination using the Mailtrap Node.js client.

```APIDOC
## [GET] /api/email-logs

### Description
Retrieves a list of email logs with optional filtering and pagination. The response includes a cursor for fetching the next page of results.

### Method
GET

### Endpoint
/api/email-logs

### Parameters
#### Query Parameters
- **filters** (object) - Optional - Filter criteria for the email logs. Supported filters include:
  - **sent_after** (string) - Optional - ISO 8601 timestamp to filter logs sent after this time.
  - **status** (object) - Optional - Filter by status. Contains `operator` (string) and `value` (string).
  - **to** (object) - Optional - Filter by recipient email. Contains `operator` (string) and `value` (string).
  - **opens_count** (object) - Optional - Filter by number of opens. Contains `operator` (string) and `value` (number).
- **search_after** (string) - Optional - Cursor for pagination. Use the `next_page_cursor` from the previous response to fetch the next page.

### Request Example
```ts
const page = await client.emailLogs.getList({
  filters: {
    sent_after: "2024-01-01T00:00:00Z",
    status: { operator: "equal", value: "delivered" },
    to: { operator: "ci_equal", value: "user@example.com" },
    opens_count: { operator: "greater_than", value: 0 },
  },
});
```

### Response
#### Success Response (200)
- **next_page_cursor** (string) - Cursor for the next page of results. Null if there are no more pages.
- **items** (array) - List of email log entries.

#### Response Example
```ts
const next = page.next_page_cursor
  ? await client.emailLogs.getList({ search_after: page.next_page_cursor })
  : null;
```
```

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

### POST /api/accounts/{account_id}/contact_imports

Source: https://github.com/mailtrap/mailtrap-nodejs/blob/main/_autodocs/api-reference/contacts-api.md

Starts an asynchronous import of contacts.

```APIDOC
## [POST] /api/accounts/{account_id}/contact_imports

### Description
Starts an asynchronous import of contacts.

### Method
POST

### Endpoint
/api/accounts/{account_id}/contact_imports

### Parameters
#### Path Parameters
- **account_id** (integer) - Required - The account ID.

#### Request Body
- **contacts** (array of objects) - Required - List of contacts to import. Each contact must have an `email` field.

### Request Example
{
  "contacts": [
    {
      "email": "a@example.com"
    }
  ]
}

### Response
#### Success Response (200)
- **id** (integer) - The import job ID.

#### Response Example
{
  "id": 1
}

```

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

### Environment variables for sandbox toggle

Source: https://github.com/mailtrap/mailtrap-nodejs/blob/main/README.md

Example environment variables for sandbox vs production switching.

```bash
MAILTRAP_API_KEY=your_api_token # https://mailtrap.io/api-tokens
MAILTRAP_USE_SANDBOX=true       # true/false toggle
MAILTRAP_INBOX_ID=123456        # Only needed for sandbox
```

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

### Usage example: createTransport with MailtrapTransport and sendMail

Source: https://github.com/mailtrap/mailtrap-nodejs/blob/main/_autodocs/types/types.md

Shows how to create a transport using MailtrapTransport and send an email with custom variables. The example uses createTransport from nodemailer and casts the mail options as MailtrapMailOptions. Note that MailtrapMailOptions is internal to the package and not re-exported.

```typescript
import { createTransport } from "nodemailer";
import { MailtrapTransport } from "mailtrap";

type SendOptions = Parameters<
  ReturnType<typeof createTransport<MailtrapResponse>>["sendMail"]
>[0]; // resolve the augmented sendMail options type from the "nodemailer" module

const transport = createTransport(MailtrapTransport({ token }));
const info = await transport.sendMail({
  from: "sender@example.com",
  to: "recipient@example.com",
  subject: "Hello",
  text: "Body",
  customVariables: { user_id: 1 },
} as MailtrapMailOptions); // MailtrapMailOptions itself is internal to the package
```

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

### Install Nodemailer dependency

Source: https://github.com/mailtrap/mailtrap-nodejs/blob/main/README.md

Install Nodemailer as a dependency for the Mailtrap transport. Use npm or Yarn.

```sh
npm install nodemailer

# or, if you are using Yarn:
yarn add nodemailer
```

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

### GET /api/inbound/folders

Source: https://github.com/mailtrap/mailtrap-nodejs/blob/main/_autodocs/endpoints-inbound.md

Retrieves a list of inbound folders.

```APIDOC
## GET /api/inbound/folders

### Description
Retrieves a list of inbound folders.

### Method
GET

### Endpoint
/api/inbound/folders

### Response
#### Success Response (200)
- **Folder[]** - Array of folder objects

#### Response Example
```json
[
  {
    "id": 1,
    "name": "Inbox"
  }
]
```
```

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

### GET /api/accounts/{accountId}/webhooks

Source: https://github.com/mailtrap/mailtrap-nodejs/blob/main/_autodocs/endpoints-marketing.md

Retrieves a list of webhooks for the account.

```APIDOC
## GET /api/accounts/{accountId}/webhooks

### Description
Retrieves a list of webhooks for the account.

### Method
GET

### Endpoint
/api/accounts/{accountId}/webhooks

### Parameters
#### Path Parameters
- **accountId** (string) - Required - The account identifier.

### Response
#### Success Response (200)
- **data** (Webhook[]) - Array of webhook objects.

```

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

### GET /api/accounts/{accountId}/projects/{projectId}

Source: https://github.com/mailtrap/mailtrap-nodejs/blob/main/_autodocs/endpoints-testing.md

Retrieves a specific project by its ID.

```APIDOC
## GET /api/accounts/{accountId}/projects/{projectId}

### Description
Retrieves a specific project by its ID.

### Method
GET

### Endpoint
/api/accounts/{accountId}/projects/{projectId}

### Parameters
#### Path Parameters
- **accountId** (string) - Required - The account ID.
- **projectId** (string) - Required - The project ID.

### Response
#### Success Response (200)
- **Project** (object) - The requested project.

#### Response Example
{
  "id": 1,
  "name": "Project 1"
}
```

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

### GET /api/accounts/{accountId}/projects

Source: https://github.com/mailtrap/mailtrap-nodejs/blob/main/_autodocs/endpoints-testing.md

Retrieves a list of projects and inboxes that the token can access.

```APIDOC
## GET /api/accounts/{accountId}/projects

### Description
Retrieves a list of projects and inboxes that the token can access.

### Method
GET

### Endpoint
/api/accounts/{accountId}/projects

### Parameters
#### Path Parameters
- **accountId** (string) - Required - The account ID.

### Response
#### Success Response (200)
- **Project[]** (array) - List of projects and inboxes.

#### Response Example
[
  {
    "id": 1,
    "name": "Project 1"
  }
]
```

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

### GET /api/accounts/{accountId}/email_templates

Source: https://github.com/mailtrap/mailtrap-nodejs/blob/main/_autodocs/endpoints-marketing.md

Retrieves a list of email templates for a given account.

```APIDOC
## GET /api/accounts/{accountId}/email_templates

### Description
Retrieves a list of email templates for a given account.

### Method
GET

### Endpoint
/api/accounts/{accountId}/email_templates

### Parameters
#### Path Parameters
- **accountId** (string) - Required - The account identifier.

### Response
#### Success Response (200)
- **Template[]** - Array of template objects.

```

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

### POST /api/accounts/{accountId}/sending_domains/{id}/send_setup_instructions

Source: https://github.com/mailtrap/mailtrap-nodejs/blob/main/_autodocs/endpoints-marketing.md

Sends setup instructions for a sending domain to a specified email address. Returns an empty response body.

```APIDOC
## POST /api/accounts/{accountId}/sending_domains/{id}/send_setup_instructions

### Description
Sends setup instructions for a sending domain to a specified email address.

### Method
POST

### Endpoint
/api/accounts/{accountId}/sending_domains/{id}/send_setup_instructions

### Parameters
#### Path Parameters
- **accountId** (string) - Required - The account identifier.
- **id** (string) - Required - The sending domain identifier.

#### Request Body
- **email** (string) - Required - The email address to send instructions to.

### Request Example
{
  "email": "user@example.com"
}

### Response
#### Success Response (200)
Empty body.
```

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

### Create bulk client with bulk: true

Source: https://github.com/mailtrap/mailtrap-nodejs/blob/main/README.md

Bulk stream example: create a client with bulk mode enabled.

```ts
const bulkClient = new MailtrapClient({ token: apiKey, bulk: true });
```

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

### GET /api/email_campaigns/{id}/stats

Source: https://github.com/mailtrap/mailtrap-nodejs/blob/main/_autodocs/api-reference/marketing-api.md

Retrieves aggregated statistics for an email campaign. All counts and rates are 0 if the campaign has never been started.

```APIDOC
## GET /api/email_campaigns/{id}/stats

### Description
Retrieves aggregated statistics for an email campaign. All counts and rates are 0 if the campaign has never been started.

### Method
GET

### Endpoint
/api/email_campaigns/{id}/stats

### Parameters
#### Path Parameters
- **id** (number) - Required - The ID of the email campaign.

#### Query Parameters
- **start_date** (string) - Optional - Start date for the statistics period.
- **end_date** (string) - Optional - End date for the statistics period.

### Response
#### Success Response (200)
- **GetEmailCampaignStatsResponse** - The aggregated statistics.

#### Response Example
```json
{
  "sent": 0,
  "opened": 0
}
```

```

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

### GET /api/email_campaigns/{id}/stats

Source: https://github.com/mailtrap/mailtrap-nodejs/blob/main/_autodocs/endpoints-marketing.md

Retrieves statistics for an email campaign, optionally filtered by start and end dates. Returns campaign stats.

```APIDOC
## GET /api/email_campaigns/{id}/stats

### Description
Retrieves statistics for an email campaign, optionally filtered by start and end dates. Returns campaign stats.

### Method
GET

### Endpoint
/api/email_campaigns/{id}/stats

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the email campaign.

#### Query Parameters
- **start_date** (string) - Optional - Start date in YYYY-MM-DD format.
- **end_date** (string) - Optional - End date in YYYY-MM-DD format.

### Response
#### Success Response (200)
- **data** (EmailCampaignStats) - Statistics for the email campaign.

#### Response Example
{
  "data": {
    "sent": 100,
    "opened": 50,
    "clicked": 20
  }
}
```

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

### Usage example for sending domains and company info

Source: https://github.com/mailtrap/mailtrap-nodejs/blob/main/_autodocs/api-reference/sending-domains-api.md

Shows how to create and configure a sending domain, then create company info for compliance and retrieve it. Requires a MailtrapClient with a token and accountId.

```ts
const client = new MailtrapClient({ token, accountId: 12345 });

// Create and configure a sending domain
const created = await client.sendingDomains.create({ domain_name: "example.com" });
await client.sendingDomains.update(created.id, {
  open_tracking_enabled: true,
  click_tracking_enabled: true,
});
await client.sendingDomains.sendSetupInstructions(created.id, "admin@example.com");

// Company info (compliance) for that domain
await client.companyInfo.create(created.id, {
  name: "Example Inc.",
  address: "1 Main St",
  city: "Springfield",
  country: "US",
  zip_code: "12345",
  website_url: "https://example.com",
  info_level: "business",
});
const info = await client.companyInfo.get(created.id);
```

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

### GET /api/tracking_opt_outs

Source: https://github.com/mailtrap/mailtrap-nodejs/blob/main/_autodocs/endpoints-marketing.md

Retrieves a list of tracking opt-outs, optionally filtered by email, start time, end time, or last ID. Returns up to 1000 records per request.

```APIDOC
## GET /api/tracking_opt_outs

### Description
Retrieves a list of tracking opt-outs, optionally filtered by email, start time, end time, or last ID. Returns up to 1000 records per request.

### Method
GET

### Endpoint
/api/tracking_opt_outs

### Parameters
#### Query Parameters
- **email** (string) - Optional - Filter by email address.
- **start_time** (string) - Optional - Filter by start time.
- **end_time** (string) - Optional - Filter by end time.
- **last_id** (string) - Optional - Pagination cursor for the last ID.

### Response
#### Success Response (200)
- **data** (array of TrackingOptOut) - List of tracking opt-outs.
- **last_id** (string) - Pagination cursor for the next page.

#### Response Example
{
  "data": [
    {
      "id": "string",
      "email": "string",
      "domain_id": "string"
    }
  ],
  "last_id": "string"
}
```

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

### EmailCampaignsBaseAPI class definition

Source: https://github.com/mailtrap/mailtrap-nodejs/blob/main/_autodocs/api-reference/marketing-api.md

Base class for the Email Campaigns API, exposing bound methods for campaign management. The class is token-scoped and does not require an account ID; the account is resolved server-side. Methods include getList, create, get, update, delete, start, schedule, cancel, terminate, reset, and getStats.

```typescript
export default class EmailCampaignsBaseAPI {
  public getList: EmailCampaignsApi["getList"];
  public create: EmailCampaignsApi["create"];
  public get: EmailCampaignsApi["get"];
  public update: EmailCampaignsApi["update"];
  public delete: EmailCampaignsApi["delete"];
  public start: EmailCampaignsApi["start"];
  public schedule: EmailCampaignsApi["schedule"];
  public cancel: EmailCampaignsApi["cancel"];
  public terminate: EmailCampaignsApi["terminate"];
  public reset: EmailCampaignsApi["reset"];
  public getStats: EmailCampaignsApi["getStats"];
  constructor(client: AxiosInstance)
}
```

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

### Switch between sandbox and production

Source: https://github.com/mailtrap/mailtrap-nodejs/blob/main/README.md

Bootstrap logic to switch between sandbox and production using environment variables.

```ts
import { MailtrapClient } from "mailtrap";

const apiKey = process.env.MAILTRAP_API_KEY;
const isSandbox = process.env.MAILTRAP_USE_SANDBOX === "true";
const inboxId = isSandbox ? Number(process.env.MAILTRAP_INBOX_ID) : undefined; // required only for sandbox

const client = new MailtrapClient({
  token: apiKey,
  sandbox: isSandbox,
  testInboxId: inboxId, // undefined is ignored for production
});

client
  .send({
    from: {
      name: "Mailtrap Test",
      email: isSandbox ? "sandbox@example.com" : "no-reply@your-domain.com",
    },
    to: [{ email: "recipient@example.com" }],
    subject: isSandbox ? "[SANDBOX] Demo email" : "Welcome onboard",
    text: "This is a minimal body for demonstration purposes.",
  })
  .then(console.log)
  .catch(console.error);
```

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

### POST /api/email_campaigns/{id}/start

Source: https://github.com/mailtrap/mailtrap-nodejs/blob/main/_autodocs/endpoints-marketing.md

Starts an email campaign. Returns the updated campaign; returns 422 on validation failure.

```APIDOC
## POST /api/email_campaigns/{id}/start

### Description
Starts an email campaign. Returns the updated campaign; returns 422 on validation failure.

### Method
POST

### Endpoint
/api/email_campaigns/{id}/start

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the email campaign.

### Response
#### Success Response (200)
- **data** (EmailCampaign) - The updated email campaign.

#### Response Example
{
  "data": {
    "id": "string",
    "name": "string",
    "status": "started"
  }
}

#### Error Response (422)
Validation failure.
```

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

### Using AttachmentsApi getList to fetch attachments

Source: https://github.com/mailtrap/mailtrap-nodejs/blob/main/_autodocs/api-reference/testing-api.md

Initializes the Mailtrap client with a token and account ID, creates a project and inbox, then retrieves messages and their attachments using the AttachmentsApi getList method.

```ts
const client = new MailtrapClient({ token, accountId: 12345 });

// Create a project and an inbox
const project = await client.testing.projects.create("My Sandbox Project");
const inbox = await client.testing.inboxes.create(project.id, "Inbox #1");

// List messages and inspect one
const messages = await client.testing.messages.get(inbox.id, { search: "Welcome" });
if (messages.length) {
  const details = await client.testing.messages.showEmailMessage(inbox.id, messages[0].id);
  const htmlSource = await client.testing.messages.getMessageHtmlSource(inbox.id, messages[0].id);
  const attachments = await client.testing.attachments.getList(inbox.id, messages[0].id);
}
```

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

### ProjectsApi.create

Source: https://github.com/mailtrap/mailtrap-nodejs/blob/main/_autodocs/api-reference/testing-api.md

Creates a new project in the sandbox. The request body must wrap the project name in a `project` object. The project name must be between 2 and 100 characters.

```APIDOC
## POST /api/accounts/{accountId}/projects

### Description
Creates a new project in the sandbox.

### Method
POST

### Endpoint
`https://mailtrap.io/api/accounts/{accountId}/projects`

### Parameters
#### Path Parameters
- `accountId` (number) - Required - The Mailtrap account ID.

#### Request Body
- `project.name` (string) - Required - The name of the project (2–100 characters).

### Request Example
```json
{
  "project": {
    "name": "My Project"
  }
}
```

### Response
#### Success Response (200)
Returns the created `Project` object.

#### Response Example
```json
{
  "id": 1,
  "name": "My Project"
}
```
```

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

### Send email with MailtrapClient: standard and template

Source: https://github.com/mailtrap/mailtrap-nodejs/blob/main/README.md

Full-featured example showing how to initialize the MailtrapClient and send both a standard email with attachments and a template-based email. The client is configured with the API token from MAILTRAP_API_KEY, and the bulk and sandbox flags default to false. The first send includes inline attachment welcome.png and custom headers; the second send uses template_uuid and template_variables.

```ts
import { MailtrapClient } from "mailtrap";
import fs from "node:fs";
import path from "node:path";

// Init Mailtrap client depending on your needs
const mailtrap = new MailtrapClient({
  token: process.env.MAILTRAP_API_KEY, // your API token
  bulk: false, // set to true for bulk email sending (false by default)
  sandbox: false, // set to true for sandbox mode (false by default)
  testInboxId: undefined, // optional, only for sandbox mode
});

const welcomeImage = fs.readFileSync(path.join(__dirname, "welcome.png"));

mailtrap
  .send({
    category: "Integration Test",
    custom_variables: {
      user_id: "45982",
      batch_id: "PSJ-12",
    },
    from: { name: "Mailtrap Test", email: "example@your-domain-here.com" },
    reply_to: { email: "reply@your-domain-here.com" },
    to: [{ name: "Jon", email: "email@example.com" }],
    cc: [{ email: "mailtrapqa@example.com" }, { email: "staging@example.com" }],
    bcc: [{ email: "mailtrapdev@example.com" }],
    subject: "Best practices of building HTML emails",
    text: "Hey! Learn the best practices of building HTML emails and play with ready-to-go templates. Mailtrap's Guide on How to Build HTML Email is live on our blog",
    html: `
      <html>
        <body>
          <p><br>Hey</br>
          Learn the best practices of building HTML emails and play with ready-to-go templates.</p>
          <p><a href="https://mailtrap.io/blog/build-html-email/">Mailtrap's Guide on How to Build HTML Email</a> is live on our blog</p>
          <img src="cid:welcome.png">
        </body>
      </html>
    `,
    attachments: [
      {
        filename: "welcome.png",
        content_id: "welcome.png",
        disposition: "inline",
        content: welcomeImage,
      },
    ],
    headers: {
      "X-Message-Source": "domain.com",
      "X-Mailer": "Mailtrap Node.js Client",
    },
  })
  .then(console.log)
  .catch(console.error);

// OR Template email sending
mailtrap
  .send({
    from: { name: "Mailtrap Test", email: "example@your-domain-here.com" },
    reply_to: { email: "reply@your-domain-here.com" },
    to: [{ name: "Jon", email: "example@gmail.com" }],
    template_uuid: "bfa432fd-0000-0000-0000-8493da283a69",
    template_variables: {
      user_name: "Jon Bush",
      next_step_link: "https://mailtrap.io/",
      get_started_link: "https://mailtrap.io/",
      onboarding_video_link: "some_video_link",
      company: {
        name: "Best Company",
        address: "Its Address",
      },
      products: [
        {
          name: "Product 1",
          price: 100,
        },
        {
          name: "Product 2",
          price: 200,
        },
      ],
      isBool: true,
      int: 123,
    },
  })
  .then(console.log)
  .catch(console.error);
```

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

### Create API token and handle permanent tokens

Source: https://github.com/mailtrap/mailtrap-nodejs/blob/main/_autodocs/api-reference/general-api.md

Creates an API token with a name and resource permissions, logging the full token value which is only returned by the create method. Also demonstrates creating a permanent token by setting expires_at to null.

```typescript
// Create a token and immediately store the returned value
const created = await client.general.apiTokens.create({
  name: "ci-token",
  resources: [
    { resource_type: "account", resource_id: 12345, access_level: 100 },
  ],
});
console.log(created.token); // only available here

// Permanent tokens
const neverExpires = await client.general.apiTokens.create({
  name: "permanent",
  expires_at: null,
});
```

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

### GET /inboxes

Source: https://github.com/mailtrap/mailtrap-nodejs/blob/main/_autodocs/api-reference/testing-api.md

Retrieves a list of all inboxes for the account.

```APIDOC
## GET /inboxes

### Description
Retrieves a list of all inboxes for the account.

### Method
GET

### Endpoint
/inboxes

### Response
#### Success Response (200)
- **Inbox[]** (array) - An array of inbox objects.

#### Response Example
```json
[
  {
    "id": 1,
    "name": "My Inbox"
  }
]
```
```

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

### GET /inboxes/{inboxId}

Source: https://github.com/mailtrap/mailtrap-nodejs/blob/main/_autodocs/api-reference/testing-api.md

Retrieves the attributes of a specific inbox.

```APIDOC
## GET /inboxes/{inboxId}

### Description
Retrieves the attributes of a specific inbox.

### Method
GET

### Endpoint
/inboxes/{inboxId}

### Parameters
#### Path Parameters
- **inboxId** (number) - Required - The inbox identifier.

### Response
#### Success Response (200)
- **Inbox** (object) - The inbox object with its attributes.

#### Response Example
```json
{
  "id": 1,
  "name": "My Inbox"
}
```
```

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

### POST /api/accounts/{accountId}/projects

Source: https://github.com/mailtrap/mailtrap-nodejs/blob/main/_autodocs/endpoints-testing.md

Creates a new project in the specified account.

```APIDOC
## POST /api/accounts/{accountId}/projects

### Description
Creates a new project in the specified account.

### Method
POST

### Endpoint
/api/accounts/{accountId}/projects

### Parameters
#### Path Parameters
- **accountId** (string) - Required - The account ID.

#### Request Body
- **project.name** (string) - Required - The name of the project.

### Request Example
{
  "project": {
    "name": "My Project"
  }
}

### Response
#### Success Response (200)
- **Project** (object) - The created project.

#### Response Example
{
  "id": 1,
  "name": "My Project"
}
```

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

### GET /api/accounts/{accountId}/inboxes

Source: https://github.com/mailtrap/mailtrap-nodejs/blob/main/_autodocs/endpoints-testing.md

Retrieves a list of inboxes for the account.

```APIDOC
## GET /api/accounts/{accountId}/inboxes

### Description
Retrieves a list of inboxes for the account.

### Method
GET

### Endpoint
/api/accounts/{accountId}/inboxes

### Parameters
#### Path Parameters
- **accountId** (string) - Required - The account ID.

### Response
#### Success Response (200)
- **Inbox[]** (array) - List of inboxes.

#### Response Example
[
  {
    "id": 1,
    "name": "Inbox 1"
  }
]
```

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

### Usage example for Mailtrap client operations

Source: https://github.com/mailtrap/mailtrap-nodejs/blob/main/_autodocs/api-reference/marketing-api.md

Shows how to use the Mailtrap client to create webhooks, manage email campaigns, create suppressions and tracking opt-outs, and list sub-accounts. Requires an account ID and organization ID.

```typescript
const client = new MailtrapClient({ token, accountId: 12345, organizationId: 9 });

// Webhooks + signature verification secret
const webhook = await client.webhooks.create({
  url: "https://example.com/hooks/mailtrap",
  webhook_type: "email_sending",
  sending_stream: "transactional",
  event_types: ["delivery", "bounce"],
});
console.log(webhook.data.signing_secret);

// Campaign lifecycle
const campaign = await client.emailCampaigns.create({
  name: "June promo",
  domain_id: 42,
  from_local_part: "no-reply",
  template_attributes: { subject: "June promo" },
});
await client.emailCampaigns.schedule(campaign.data.id, { datetime: "2024-06-01T09:00:00Z" });
await client.emailCampaigns.cancel(campaign.data.id);

// Suppression + opt-out management
await client.suppressions.create({
  email: "bad@example.com",
  domain_id: 42,
  sending_stream: "transactional",
});
await client.trackingOptOuts.create({ email: "user@example.com", domain_id: 42 });

// Sub-accounts under the organization
const subs = await client.organizations.subAccounts.getList();
```

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

### ProjectsApi.getList

Source: https://github.com/mailtrap/mailtrap-nodejs/blob/main/_autodocs/api-reference/testing-api.md

Retrieves a list of all projects associated with the account.

```APIDOC
## GET /api/accounts/{accountId}/projects

### Description
Retrieves a list of all projects in the sandbox.

### Method
GET

### Endpoint
`https://mailtrap.io/api/accounts/{accountId}/projects`

### Parameters
#### Path Parameters
- `accountId` (number) - Required - The Mailtrap account ID.

### Response
#### Success Response (200)
Returns an array of `Project` objects.

#### Response Example
```json
[
  {
    "id": 1,
    "name": "Project One"
  }
]
```
```

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

### GET /api/inbound/folders/{folderId}

Source: https://github.com/mailtrap/mailtrap-nodejs/blob/main/_autodocs/endpoints-inbound.md

Retrieves a specific inbound folder by its ID.

```APIDOC
## GET /api/inbound/folders/{folderId}

### Description
Retrieves a specific inbound folder by its ID.

### Method
GET

### Endpoint
/api/inbound/folders/{folderId}

### Parameters
#### Path Parameters
- **folderId** (string) - Required - The ID of the folder to retrieve.

### Response
#### Success Response (200)
- **Folder** - The folder object

#### Response Example
```json
{
  "id": 1,
  "name": "Inbox"
}
```
```

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

### Contacts API usage example

Source: https://github.com/mailtrap/mailtrap-nodejs/blob/main/_autodocs/api-reference/contacts-api.md

Shows the main operations of the Contacts API: creating a contact list and a contact, updating contact list membership, tracking a custom event, performing an async import, and exporting filtered contacts. Requires a MailtrapClient instance with a token and accountId.

```ts
const client = new MailtrapClient({ token, accountId: 12345 });

// Create a contact and put it on a list
const list = await client.contactLists.create({ name: "Newsletter" });
const created = await client.contacts.create({
  email: "user@example.com",
  fields: { first_name: "John" },
  list_ids: [list.id],
});
console.log(created.data);

// Update by id or email, add/remove list membership
await client.contacts.update(created.data.id, {
  list_ids_included: [list.id],
  list_ids_excluded: [],
});

// Track a custom event
await client.contactEvents.create(created.data.id, {
  name: "signed_up",
  params: { source: "referral" },
});

// Async import
const importJob = await client.contactImports.create({
  contacts: [{ email: "a@example.com" }],
});
const status = await client.contactImports.get(importJob.id);

// Export filtered contacts
const exportJob = await client.contactExports.create({
  filters: [
    { name: "list_id", operator: "equal", value: [list.id] },
  ],
});
```

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

### GET /api/accounts/{accountId}/contacts/fields

Source: https://github.com/mailtrap/mailtrap-nodejs/blob/main/_autodocs/endpoints-contacts.md

Retrieves a list of contact fields.

```APIDOC
## GET /api/accounts/{accountId}/contacts/fields

### Description
Retrieves a list of contact fields.

### Method
GET

### Endpoint
/api/accounts/{accountId}/contacts/fields

### Parameters
#### Path Parameters
- **accountId** (string) - Required - The account ID.

### Response
#### Success Response (200)
- **data** (ContactField[]) - Array of contact fields.

#### Response Example
{
  "data": []
}
```

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

### POST /api/accounts/{account_id}/contact_exports

Source: https://github.com/mailtrap/mailtrap-nodejs/blob/main/_autodocs/api-reference/contacts-api.md

Starts an export of filtered contacts.

```APIDOC
## [POST] /api/accounts/{account_id}/contact_exports

### Description
Starts an export of filtered contacts.

### Method
POST

### Endpoint
/api/accounts/{account_id}/contact_exports

### Parameters
#### Path Parameters
- **account_id** (integer) - Required - The account ID.

#### Request Body
- **filters** (array of objects) - Optional - Filters to apply to the export. Each filter has `name`, `operator`, and `value` fields.

### Request Example
{
  "filters": [
    {
      "name": "list_id",
      "operator": "equal",
      "value": [1]
    }
  ]
}

### Response
#### Success Response (200)
- **id** (integer) - The export job ID.

#### Response Example
{
  "id": 1
}

```

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

### MailtrapClient Constructor

Source: https://github.com/mailtrap/mailtrap-nodejs/blob/main/_autodocs/api-reference/mailtrap-client.md

Constructor for the MailtrapClient class, initializing the client with configuration options.

```APIDOC
## [CONSTRUCTOR] MailtrapClient

### Description
Initializes the Mailtrap client with an Axios instance configured for Mailtrap API requests. Sets up authentication, headers, and interceptors for sending and error handling.

### Method
Constructor

### Endpoint
N/A (SDK constructor)

### Parameters
- **token** (string) - Required - Mailtrap API token; sent as `Authorization: Bearer <token>` on every request
- **testInboxId** (number) - Optional - Sandbox inbox ID; only used when `sandbox` is enabled
- **accountId** (number) - Optional - Mailtrap account ID; required by most getters
- **organizationId** (number) - Optional - Organization ID; required by the `organizations` getter
- **bulk** (boolean) - Optional - Default: `false` - If `true`, sending uses the bulk endpoint host
- **sandbox** (boolean) - Optional - Default: `false` - If `true`, sending uses the sandbox (testing) endpoint host
- **userAgent** (string) - Optional - Default: `USER_AGENT` constant - Overrides the default User-Agent header

### Request Example
```ts
const client = new MailtrapClient({
  token: "YOUR_API_TOKEN",
  testInboxId: 12345,
  accountId: 67890,
  organizationId: 111213,
  bulk: false,
  sandbox: true,
  userAgent: "my-app/1.0"
});
```

### Response
#### Success Response
- No return value (constructor)

#### Response Example
N/A

```

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

### POST /api/inbound/folders

Source: https://github.com/mailtrap/mailtrap-nodejs/blob/main/_autodocs/endpoints-inbound.md

Creates a new inbound folder.

```APIDOC
## POST /api/inbound/folders

### Description
Creates a new inbound folder.

### Method
POST

### Endpoint
/api/inbound/folders

### Parameters
#### Request Body
- **name** (string) - Required - The name of the folder.

### Request Example
```json
{
  "name": "My Folder"
}
```

### Response
#### Success Response (200)
- **Folder** - The created folder object

#### Response Example
```json
{
  "id": 2,
  "name": "My Folder"
}
```
```

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

### GET /api/accounts/{account_id}/contact_imports/{import_id}

Source: https://github.com/mailtrap/mailtrap-nodejs/blob/main/_autodocs/api-reference/contacts-api.md

Retrieves the status of an import job.

```APIDOC
## [GET] /api/accounts/{account_id}/contact_imports/{import_id}

### Description
Retrieves the status of an import job.

### Method
GET

### Endpoint
/api/accounts/{account_id}/contact_imports/{import_id}

### Parameters
#### Path Parameters
- **account_id** (integer) - Required - The account ID.
- **import_id** (integer) - Required - The import job ID.

### Response
#### Success Response (200)
- **status** (string) - The status of the import job.

#### Response Example
{
  "status": "completed"
}

```

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

### POST /api/email_campaigns

Source: https://github.com/mailtrap/mailtrap-nodejs/blob/main/_autodocs/endpoints-marketing.md

Creates a new email campaign as a draft. Requires template_attributes.subject in the request body. Returns the created campaign.

```APIDOC
## POST /api/email_campaigns

### Description
Creates a new email campaign as a draft. Requires template_attributes.subject in the request body. Returns the created campaign.

### Method
POST

### Endpoint
/api/email_campaigns

### Parameters
#### Request Body
- **template_attributes** (object) - Required - Contains template attributes, including subject.
  - **subject** (string) - Required - The subject of the email campaign.

### Request Example
{
  "template_attributes": {
    "subject": "Welcome to our service"
  }
}

### Response
#### Success Response (200)
- **data** (EmailCampaign) - The created email campaign (draft).

#### Response Example
{
  "data": {
    "id": "string",
    "name": "string",
    "status": "draft"
  }
}
```

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

### GET /api/accounts/{account_id}/stats/grouped-by-domain

Source: https://github.com/mailtrap/mailtrap-nodejs/blob/main/_autodocs/api-reference/email-logs-stats-api.md

Retrieves email statistics grouped by domain.

```APIDOC
## [GET] /api/accounts/{account_id}/stats/grouped-by-domain

### Description
Retrieves email statistics grouped by domain.

### Method
GET

### Endpoint
/api/accounts/{account_id}/stats/grouped-by-domain

### Parameters
#### Query Parameters
- **start_date** (string) - Required - Start date in YYYY-MM-DD format.
- **end_date** (string) - Required - End date in YYYY-MM-DD format.

### Response
#### Success Response (200)
- **data** (array) - List of statistics grouped by domain.

#### Response Example
```json
{
  "data": [
    { "domain": "example.com", "delivery_rate": 0.95 }
  ]
}
```
```

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

### POST /api/tracking_opt_outs

Source: https://github.com/mailtrap/mailtrap-nodejs/blob/main/_autodocs/endpoints-marketing.md

Creates a new tracking opt-out for a given email and domain. Returns the created tracking opt-out object.

```APIDOC
## POST /api/tracking_opt_outs

### Description
Creates a new tracking opt-out for a given email and domain. Returns the created tracking opt-out object.

### Method
POST

### Endpoint
/api/tracking_opt_outs

### Parameters
#### Request Body
- **email** (string) - Required - The email address to opt out.
- **domain_id** (string) - Required - The domain ID associated with the opt-out.

### Request Example
{
  "email": "user@example.com",
  "domain_id": "12345"
}

### Response
#### Success Response (200)
- **data** (TrackingOptOut) - The created tracking opt-out object.

#### Response Example
{
  "data": {
    "id": "string",
    "email": "string",
    "domain_id": "string"
  }
}
```

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

### GET /api/accounts/{accountId}/inboxes/{inboxId}

Source: https://github.com/mailtrap/mailtrap-nodejs/blob/main/_autodocs/endpoints-testing.md

Retrieves the attributes of a specific inbox.

```APIDOC
## GET /api/accounts/{accountId}/inboxes/{inboxId}

### Description
Retrieves the attributes of a specific inbox.

### Method
GET

### Endpoint
/api/accounts/{accountId}/inboxes/{inboxId}

### Parameters
#### Path Parameters
- **accountId** (string) - Required - The account ID.
- **inboxId** (string) - Required - The inbox ID.

### Response
#### Success Response (200)
- **Inbox** (object) - The inbox attributes.

#### Response Example
{
  "id": 1,
  "name": "Inbox 1"
}
```

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

### POST /api/accounts/{accountId}/api_tokens

Source: https://github.com/mailtrap/mailtrap-nodejs/blob/main/_autodocs/endpoints.md

Creates a new API token for the account. The full token is returned only once in the response.

```APIDOC
## POST /api/accounts/{accountId}/api_tokens

### Description
Creates a new API token for the account. The full token is returned only once in the response.

### Method
POST

### Endpoint
/api/accounts/{accountId}/api_tokens

### Parameters
#### Path Parameters
- **accountId** (integer) - Required - The ID of the account.

#### Request Body
- **name** (string) - Required - The name of the token.
- **expires_at** (string) - Optional - Expiration date in ISO format. Omit for server default, null for never expires.
- **resources** (array) - Optional - List of resources the token can access.

### Request Example
{
  "name": "My Token",
  "expires_at": "2025-12-31T23:59:59Z"
}

### Response
#### Success Response (200)
- **body** (object) - ApiTokenWithToken object containing the full token (one-time).

#### Response Example
{
  "id": 1,
  "name": "My Token",
  "token": "full-token-value"
}

```

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

### GET /api/accounts

Source: https://github.com/mailtrap/mailtrap-nodejs/blob/main/_autodocs/api-reference/general-api.md

Retrieves all Mailtrap accounts accessible with the current API token.

```APIDOC
## GET /api/accounts

### Description
Returns a list of Mailtrap accounts the API token has access to.

### Method
GET

### Endpoint
https://mailtrap.io/api/accounts

### Response
#### Success Response (200)
- **body** (User[]) - List of Mailtrap accounts the API token has access to.

### Response Example
```json
[
  {
    "id": 1,
    "name": "My Account"
  }
]
```
```

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

### Using MailtrapClient getters with accountId and organizationId

Source: https://github.com/mailtrap/mailtrap-nodejs/blob/main/_autodocs/api-reference/mailtrap-client.md

Shows how to instantiate MailtrapClient with token, accountId, and organizationId, then use the testing, general, and organizations getters to fetch data. The organizations getter requires organizationId; otherwise it throws MailtrapError(ORGANIZATION_ID_MISSING).

```ts
const client = new MailtrapClient({ token, accountId: 12345, organizationId: 9 });

const projects = await client.testing.projects.getList();
const accounts = await client.general.accounts.getAllAccounts();
const subAccounts = await client.organizations.subAccounts.getList();
```

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

### POST /api/accounts/{accountId}/contacts/imports

Source: https://github.com/mailtrap/mailtrap-nodejs/blob/main/_autodocs/endpoints-contacts.md

Creates a contact import job.

```APIDOC
## POST /api/accounts/{accountId}/contacts/imports

### Description
Creates a contact import job.

### Method
POST

### Endpoint
/api/accounts/{accountId}/contacts/imports

### Parameters
#### Path Parameters
- **accountId** (string) - Required - The account ID.

#### Request Body
- **contacts** (array) - Required - Array of contact objects. Each contact has `email` (required), `fields?`, `list_ids_included?`, `list_ids_excluded?`.

### Request Example
{
  "contacts": [
    {
      "email": "user@example.com"
    }
  ]
}

### Response
#### Success Response (200)
- **ContactImportResponse** - The import response with `status` field: `created`, `started`, `finished`, or `failed`.

#### Response Example
{
  "status": "created"
}
```

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

### GET /inboxes/{inboxId}/messages

Source: https://github.com/mailtrap/mailtrap-nodejs/blob/main/_autodocs/api-reference/testing-api.md

Retrieves a list of messages from the sandbox inbox.

```APIDOC
## [GET] /inboxes/{inboxId}/messages

### Description
Retrieves a list of messages from the sandbox inbox.

### Method
GET

### Endpoint
/inboxes/{inboxId}/messages

### Parameters
#### Path Parameters
- **inboxId** (number) - Required - The ID of the inbox.

#### Query Parameters
- **last_id** (number) - Optional - The ID of the last message for pagination.
- **page** (number) - Optional - The page number for pagination.
- **search** (string) - Optional - A search query to filter messages.

### Response
#### Success Response (200)
- **Message[]** (array) - A list of message objects.

### Response Example
[
  {
    "id": 1,
    "subject": "Hello"
  }
]
```

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

### GET /api/accounts/{accountId}/webhooks/{id}

Source: https://github.com/mailtrap/mailtrap-nodejs/blob/main/_autodocs/endpoints-marketing.md

Retrieves a single webhook by its ID.

```APIDOC
## GET /api/accounts/{accountId}/webhooks/{id}

### Description
Retrieves a single webhook by its ID.

### Method
GET

### Endpoint
/api/accounts/{accountId}/webhooks/{id}

### Parameters
#### Path Parameters
- **accountId** (string) - Required - The account identifier.
- **id** (string) - Required - The webhook identifier.

### Response
#### Success Response (200)
- **data** (Webhook) - The webhook object. Does not include the signing secret.

```

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

### Folder and FolderParams interfaces

Source: https://github.com/mailtrap/mailtrap-nodejs/blob/main/_autodocs/types/types-inbound.md

Defines the Folder and FolderParams interfaces used by FoldersApi. Folder is returned by getList/get, while FolderParams is sent as the body for create/update.

```ts
export interface Folder {
  id: number;
  name: string;
}

export interface FolderParams {
  name: string;
}
```
Tokens:
Raw