To get the most out of this official Mailtrap.io Node.js SDK:
You can install the package via npm or yarn:
npm install mailtrap
# or, if you are using Yarn:
yarn add mailtrap
You should use ES modules or CommonJS imports in your application to load the package.
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, // You can create your API key here https://mailtrap.io/api-tokens
});
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);
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 ? "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:
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.
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);
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:
Email API:
sending/minimal.tsbulk/send-mail.tssending/template.tsbulk/send-mail.tsbatch/transactional.tsbatch/bulk.tsbatch/template.tsbatch/template.tssending-domains/everything.tsstats/everything.tsemail-logs/everything.tsEmail Sandbox (Testing):
testing/send-mail.tstesting/template.tsbatch/sandbox.tsbatch/sandbox.tstesting/messages.tstesting/inboxes.tstesting/projects.tstesting/attachments.tsContact management:
contacts/everything.tscontact-lists/everything.tscontact-fields/everything.tscontact-imports/everything.ts, contact-exports/everything.tscontact-events/everything.tsGeneral API:
templates/everything.tssending/suppressions.tsgeneral/billing.tsgeneral/accounts.tsgeneral/permissions.tsgeneral/account-accesses.tsBug 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.
The package is available as open source under the terms of the MIT License.
Everyone interacting in the Mailtrap project's codebases, issue trackers, chat rooms, and mailing lists is expected to follow the code of conduct.
Versions of this package up to 2.0.2 were an unofficial client developed by @vchin. Package version 3 is a completely new package.
FAQs
Official mailtrap.io API client
The npm package mailtrap receives a total of 30,414 weekly downloads. As such, mailtrap popularity was classified as popular.
We found that mailtrap demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
Malicious Namastex.ai npm packages appear to replicate TeamPCP-style Canister Worm tradecraft, including exfiltration and self-propagation.
Product
Explore exportable charts for vulnerabilities, dependencies, and usage with Reports, Socket’s new extensible reporting framework.
Product
Socket for Jira lets teams turn alerts into Jira tickets with manual creation, automated ticketing rules, and two-way sync.