From 523d485d9fc5d5c543e3c2d1ef32900c5569c65e Mon Sep 17 00:00:00 2001 From: Narek Hovhannisyan Date: Thu, 13 Nov 2025 17:07:18 +0400 Subject: [PATCH 1/3] Update README.md to enhance installation and usage instructions, improve clarity on API features, and add examples for email sending and contact management functionalities. --- README.md | 315 ++++++++++++++++++++++++++++++++++++------------------ 1 file changed, 209 insertions(+), 106 deletions(-) diff --git a/README.md b/README.md index d038160..bd9de71 100644 --- a/README.md +++ b/README.md @@ -5,83 +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: +To get the most 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 - - 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 = ""; -const SENDER_EMAIL = ""; -const RECIPIENT_EMAIL = ""; +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 }); +``` +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 +``` -const sender = { name: "Mailtrap Test", email: SENDER_EMAIL }; +Bootstrap logic: + +```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: 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: ` + + +


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

+ + + + `, + 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); @@ -92,98 +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 info – (no example yet) ← add in future -## 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 From 9bc80a346cba61dc15d50e92cff3b3fada685b65 Mon Sep 17 00:00:00 2001 From: Narek Hovhannisyan Date: Mon, 17 Nov 2025 17:14:43 +0400 Subject: [PATCH 2/3] fix: update code block syntax in README.md for better clarity --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 9d6e20a..5cd3956 100644 --- a/README.md +++ b/README.md @@ -56,7 +56,7 @@ Mailtrap lets you test safely in the Email Sandbox and then switch to Production Example `.env` variables (or export in shell): -``` +```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 From b1d444f89e69e1f5e0e43c59dfcc687dc126e028 Mon Sep 17 00:00:00 2001 From: Narek Hovhannisyan Date: Mon, 17 Nov 2025 17:20:59 +0400 Subject: [PATCH 3/3] fix: correct wording in README.md for improved clarity --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 5cd3956..707dd41 100644 --- a/README.md +++ b/README.md @@ -7,7 +7,7 @@ ## Prerequisites -To get the most of this official Mailtrap.io Node.js SDK: +To get the most out of this official Mailtrap.io Node.js SDK: - [Create a Mailtrap account](https://mailtrap.io/signup)