mailtrap

v4.4.0

Published

5 days ago

Official mailtrap.io API client

0High
0Medium
0Low

mailtrap

Mailtrap Node.js client - Official

Prerequisites

To get the most out of this official Mailtrap.io Node.js SDK:

Installation

You can install the package via npm or yarn:

npm install mailtrap

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

Usage

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:

import { MailtrapClient } from "mailtrap";

const mailtrap = new MailtrapClient({
  token: process.env.MAILTRAP_API_KEY, // your API key here https://mailtrap.io/api-tokens
});

mailtrap
  .send({
    from: { name: "Mailtrap Test", email: "[email protected]" },
    to: [{ email: "[email protected]" }],
    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):

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:

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 ? "[email protected]" : "[email protected]",
    },
    to: [{ email: "[email protected]" }],
    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:

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

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: "[email protected]" },
    reply_to: { email: "[email protected]" },
    to: [{ name: "Jon", email: "[email protected]" }],
    cc: [{ email: "[email protected]" }, { email: "[email protected]" }],
    bcc: [{ email: "[email protected]" }],
    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: "[email protected]" },
    reply_to: { email: "[email protected]" },
    to: [{ name: "Jon", email: "[email protected]" }],
    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);

Nodemailer Transport

NOTE: Nodemailer is needed as a dependency.

npm install nodemailer

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

If you're using TypeScript, install @types/nodemailer as a devDependency:

npm install -D @types/nodemailer

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

You can provide Mailtrap-specific keys like category, custom_variables, template_uuid, and template_variables.

See transport usage below:

Transport

Supported functionality & Examples

Email API:

Send an email (Transactional stream) – sending/minimal.ts
Send an email (Bulk stream) – bulk/send-mail.ts
Send an email with a Template (Transactional) – sending/template.ts
Send an email with a Template (Bulk) – bulk/send-mail.ts
Batch send (Transactional) – batch/transactional.ts
Batch send (Bulk) – batch/bulk.ts
Batch send with Template (Transactional) – batch/template.ts
Batch send with Template (Bulk) – batch/template.ts
Sending domain management CRUD – sending-domains/everything.ts

Email Sandbox (Testing):

Send an email (Sandbox) – testing/send-mail.ts
Send an email with a Template (Sandbox) – testing/template.ts
Batch send (Sandbox) – batch/sandbox.ts
Batch send with Template (Sandbox) – batch/sandbox.ts
Message management CRUD – testing/messages.ts
Inbox management CRUD – testing/inboxes.ts
Project management CRUD – testing/projects.ts
Attachments operations – testing/attachments.ts

Contact management:

Contacts CRUD & listing – contacts/everything.ts
Contact lists CRUD – contact-lists/everything.ts
Custom fields CRUD – contact-fields/everything.ts
Import/Export – contact-imports/everything.ts, contact-exports/everything.ts
Events – contact-events/everything.ts

General API:

Templates CRUD – templates/everything.ts
Suppressions (find & delete) – sending/suppressions.ts
Billing info – general/billing.ts
Accounts info – general/accounts.ts
Permissions listing – general/permissions.ts
Users listing – general/account-accesses.ts

Contributing

Bug reports and pull requests are welcome on GitHub. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the code of conduct.

License

The package is available as open source under the terms of the MIT License.

Code of Conduct

Everyone interacting in the Mailtrap project's codebases, issue trackers, chat rooms, and mailing lists is expected to follow the code of conduct.

Compatibility with previous releases

Versions of this package up to 2.0.2 were an unofficial client developed by @vchin. Package version 3 is a completely new package.