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 mailtrapYou 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, // 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);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 sandboxBootstrap 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.
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);NOTE: Nodemailer is needed as a dependency.
npm install nodemailer
# or, if you are using Yarn:
yarn add nodemailerIf 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/nodemailerYou can provide Mailtrap-specific keys like category, custom_variables, template_uuid, and template_variables.
See transport usage below:
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
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.
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.
![@dependabot[bot]](https://avatars.githubusercontent.com/in/29110?s=64&v=4){kind=small}
