mailtrap · narekhovhannisyan · Nov 17, 2025 · Nov 13, 2025 · Nov 17, 2025 · Nov 17, 2025
diff --git a/README.md b/README.md
@@ -5,84 +5,192 @@
 [![NPM](https://shields.io/npm/v/mailtrap?logo=npm&logoColor=white)](https://www.npmjs.com/package/mailtrap)
 [![downloads](https://shields.io/npm/d18m/mailtrap)](https://www.npmjs.com/package/mailtrap)
 
-
 ## Prerequisites
 
 To get the most out of this official Mailtrap.io Node.js SDK:
+
 - [Create a Mailtrap account](https://mailtrap.io/signup)
-- [Verify your domain](https://mailtrap.io/sending/domains)
 
-## Supported functionality
-
-This NPM package offers integration with the [official API](https://api-docs.mailtrap.io/) for [Mailtrap](https://mailtrap.io).
-
-Quickly integrate Mailtrap with your Node.js app.
-
-Currently, with this SDK you can:
-- Email API/SMTP
-  - Send an email
-  - Send an email with a template
-  - Send a batch of emails
-- Email Sandbox (Testing)
-  - Send an email
-  - Send an email with a template
-  - Message management
-  - Inbox management
-  - Project management
-- Contact management
-  - Contact Events
-  - Contact Exports
-  - Contact Fields
-  - Contact Imports
-  - Contact Lists
-  - Contacts
-- General
-  - Templates
-  - Suppressions management
-  - Account access management
-  - Permissions management
-  - Billing usage management
-  - List accounts you have access to
-
+- [Verify your domain](https://mailtrap.io/sending/domains)
 
 ## Installation
 
-Use yarn or npm to install the package:
+You can install the package via [npm](https://www.npmjs.com/) or [yarn](https://yarnpkg.com/):
 
-```sh
-yarn add mailtrap
-
-# or, if you are using NPM:
+```bash
 npm install mailtrap
-```
 
+# or, if you are using Yarn:
+yarn add mailtrap
+```
 
 ## Usage
 
-### Minimal
+You should use ES modules or CommonJS imports in your application to load the package.
+
+### Minimal usage (Transactional sending)
+
+The quickest way to send a single transactional email with only the required parameters:
 
 ```ts
-import { MailtrapClient } from "mailtrap"
+import { MailtrapClient } from "mailtrap";
 
-/**
- * For this example to work, you need to set up a sending domain,
- * and obtain a token that is authorized to send from the domain.
- */
+const mailtrap = new MailtrapClient({
+  token: process.env.MAILTRAP_API_KEY, // your API key here https://mailtrap.io/api-tokens
+});
 
-const TOKEN = "<YOUR-TOKEN-HERE>";
-const SENDER_EMAIL = "<SENDER@YOURDOMAIN.COM>";
-const RECIPIENT_EMAIL = "<RECIPIENT@EMAIL.COM>";
+mailtrap
+  .send({
+    from: { name: "Mailtrap Test", email: "sender@example.com" },
+    to: [{ email: "recipient@example.com" }],
+    subject: "Hello from Mailtrap Node.js",
+    text: "Plain text body",
+  })
+  .then(console.log)
+  .catch(console.error);
+```
+
+### Sandbox vs Production (easy switching)
+
+Mailtrap lets you test safely in the Email Sandbox and then switch to Production (Sending) with one flag.
+
+Example `.env` variables (or export in shell):
 
-const client = new MailtrapClient({ token: TOKEN });
+```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
+```
+
+Bootstrap logic:
+
+```ts
+import { MailtrapClient } from "mailtrap";
 
-const sender = { name: "Mailtrap Test", email: SENDER_EMAIL };
+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: sender,
-    to: [{ email: RECIPIENT_EMAIL }],
-    subject: "Hello from Mailtrap!",
-    text: "Welcome to Mailtrap Sending!",
+    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);
+```
+
+Bulk stream example (optional) differs only by setting `bulk: true`:
+
+```ts
+const bulkClient = new MailtrapClient({ token: apiKey, bulk: true });
+```
+
+Recommendations:
+
+- Toggle sandbox with `MAILTRAP_USE_SANDBOX`.
+
+- Use separate API tokens for Production and Sandbox.
+
+- Keep initialisation in a single factory object/service so that switching is centralised.
+
+### Full-featured usage example
+
+```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);
@@ -93,99 +201,92 @@ client
 > NOTE: [Nodemailer](https://www.npmjs.com/package/nodemailer) is needed as a dependency.
 
 ```sh
-yarn add nodemailer
-
-# or, if you are using NPM:
 npm install nodemailer
+
+# or, if you are using Yarn:
+yarn add nodemailer
 ```
 
-If you're using TypeScript, install `@types/nodemailer` as a `devDependency`.
+If you're using TypeScript, install `@types/nodemailer` as a `devDependency`:
 
 ```sh
-yarn add --dev @types/nodemailer
-
-# or, if you are using NPM:
 npm install -D @types/nodemailer
+
+# or, if you are using Yarn:
+yarn add --dev @types/nodemailer
 ```
 
-You can provide Mailtrap-specific keys like `category`, `customVariables`, `templateUuid`, and `templateVariables`.
+You can provide Mailtrap-specific keys like `category`, `custom_variables`, `template_uuid`, and `template_variables`.
 
 See transport usage below:
 
 - [Transport](examples/sending/transport.ts)
 
-## Examples
+## Supported functionality & Examples
+
+Email API:
+
+- Send an email (Transactional stream) – [`sending/minimal.ts`](examples/sending/minimal.ts)
+
+- Send an email (Bulk stream) – [`bulk/send-mail.ts`](examples/bulk/send-mail.ts)
+
+- Send an email with a Template (Transactional) – [`sending/template.ts`](examples/sending/template.ts)
 
-Refer to the [`examples`](examples) folder for the source code of this and other advanced examples.
+- Send an email with a Template (Bulk) – [`bulk/send-mail.ts`](examples/bulk/send-mail.ts)
 
-### Contact Events API
+- Batch send (Transactional) – [`batch/transactional.ts`](examples/batch/transactional.ts)
 
-- [Contact Events](examples/contact-events/everything.ts)
+- Batch send (Bulk) – [`batch/bulk.ts`](examples/batch/bulk.ts)
 
-### Contact Exports API
+- Batch send with Template (Transactional) – [`batch/template.ts`](examples/batch/template.ts)
 
-- [Contact Exports](examples/contact-exports/everything.ts)
+- Batch send with Template (Bulk) – [`batch/template.ts`](examples/batch/template.ts)
 
-### Contact Fields API
+- Sending domain management CRUD – [`sending-domains/everything.ts`](examples/sending-domains/everything.ts)
 
-- [Contact Fields](examples/contact-fields/everything.ts)
+Email Sandbox (Testing):
 
-### Contact Imports API
+- Send an email (Sandbox) – [`testing/send-mail.ts`](examples/testing/send-mail.ts)
 
-- [Contact Imports](examples/contact-imports/everything.ts)
+- Send an email with a Template (Sandbox) – [`testing/template.ts`](examples/testing/template.ts)
 
-### Contact Lists API
+- Batch send (Sandbox) – [`batch/sandbox.ts`](examples/batch/sandbox.ts)
 
-- [Contact Lists](examples/contact-lists/everything.ts)
+- Batch send with Template (Sandbox) – [`batch/sandbox.ts`](examples/batch/sandbox.ts)
 
-### Contacts API
+- Message management CRUD – [`testing/messages.ts`](examples/testing/messages.ts)
 
-- [Contacts](examples/contacts/everything.ts)
+- Inbox management CRUD – [`testing/inboxes.ts`](examples/testing/inboxes.ts)
 
-### Sending API
+- Project management CRUD – [`testing/projects.ts`](examples/testing/projects.ts)
 
-- [Advanced](examples/sending/everything.ts)
-- [Minimal](examples/sending/minimal.ts)
-- [Send email using template](examples/sending/template.ts)
-- [Suppressions management](examples/sending/suppressions.ts)
-- [Nodemailer transport](examples/sending/transport.ts)
+- Attachments operations – [`testing/attachments.ts`](examples/testing/attachments.ts)
 
-### Batch Sending API
+Contact management:
 
-- [Transactional emails](examples/batch/transactional.ts)
-- [Bulk emails](examples/batch/bulk.ts)
-- [Sandbox emails](examples/batch/sandbox.ts)
-- [Emails from template](examples/batch/template.ts)
+- Contacts CRUD & listing – [`contacts/everything.ts`](examples/contacts/everything.ts)
 
-### Bulk Sending API
+- Contact lists CRUD – [`contact-lists/everything.ts`](examples/contact-lists/everything.ts)
 
-- [Send mail](examples/bulk/send-mail.ts)
-- [Nodemailer Transport](examples/bulk/transport.ts)
+- Custom fields CRUD – [`contact-fields/everything.ts`](examples/contact-fields/everything.ts)
 
-### Templates API
+- Import/Export – [`contact-imports/everything.ts`](examples/contact-imports/everything.ts), [`contact-exports/everything.ts`](examples/contact-exports/everything.ts)
 
-- [Templates](examples/templates/everything.ts)
+- Events – [`contact-events/everything.ts`](examples/contact-events/everything.ts)
 
-### Email Sandbox (Testing) API
+General API:
 
-- [Attachments](examples/testing/attachments.ts)
-- [Inboxes](examples/testing/inboxes.ts)
-- [Messages](examples/testing/messages.ts)
-- [Projects](examples/testing/projects.ts)
-- [Send mail using template](examples/testing/template.ts)
+- Templates CRUD – [`templates/everything.ts`](examples/templates/everything.ts)
 
-### General API
+- Suppressions (find & delete) – [`sending/suppressions.ts`](examples/sending/suppressions.ts)
 
-- [List User & Invite account accesses](examples/general/account-accesses.ts)
-- [Remove account access](examples/general/accounts.ts)
-- [Permissions](examples/general/permissions.ts)
-- [Billing usage](examples/general/billing.ts)
+- Billing info – [`general/billing.ts`](examples/general/billing.ts)
 
-## Development
+- Accounts info – [`general/accounts.ts`](examples/general/accounts.ts)
 
-This library is developed using [TypeScript](https://www.typescriptlang.org).
+- Permissions listing – [`general/permissions.ts`](examples/general/permissions.ts)
 
-Use `yarn lint` to perform linting with [ESLint](https://eslint.org).
+- Users listing – [`general/account-accesses.ts`](examples/general/account-accesses.ts)
 
 ## Contributing