Registry / communication / smtpapi

smtpapi

JSON →
library0.4.12jsnpmunverified

The `smtpapi` library is an official Twilio SendGrid Node.js module designed to programmatically construct X-SMTPAPI headers. These headers enable advanced email features such as scheduled sends, substitutions, categories, unique arguments, and recipient lists for emails sent via SendGrid's SMTP API or older V2 Mail Send API. The current stable version is 1.4.7. The package has a maintenance-focused release cadence, with recent updates primarily consisting of chore and documentation improvements rather than new features. While functional, it's crucial to note that newer SendGrid V3 Mail Send API integrations typically utilize `custom_args` directly within the API request body, which differs from the X-SMTPAPI header approach this library facilitates. This library serves as a dedicated tool for those using the SMTP or V2 API methods that rely on the X-SMTPAPI header format.

communication
npm install smtpapi
github ↗package ↗homepage ↗
INSTALL
IMPORT
SIG · SMTPAPI
S
smtpapi
communicationjavascriptv0.4.12
Install
—
Import
—
Disk
—
Pass rate
0/ 6
Env Coverage0 / 6
glibc
18–22
musl
18–22
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18–226 runs
build_error
glibc
node 18–226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

smtpapi (Constructor)
✓ const Smtpapi = require('smtpapi');
✗ import Smtpapi from 'smtpapi';
This library is primarily CommonJS (CJS). Direct ES module (ESM) `import` syntax will not work without Node.js interoperability configuration or dynamic `import()` for CJS modules.
Smtpapi instance
✓ const header = new Smtpapi();
✗ const header = Smtpapi();
The `smtpapi` export is a constructor function and must be instantiated using the `new` keyword.
Generated JSON string
✓ const headerString = header.jsonString();
✗ const headerObject = header.json();
The method `jsonString()` is used to retrieve the fully formatted JSON string suitable for the `X-SMTPAPI` header. There is no direct `json()` method that returns a raw JavaScript object.

Demonstrates how to initialize the `smtpapi` header, add recipients, unique arguments, categories, and substitutions, then retrieve the complete JSON string for inclusion in an email's X-SMTPAPI header.

const Smtpapi = require('smtpapi'); // Create a new SMTPAPI header instance const header = new Smtpapi(); // Add multiple recipients to the 'to' field header.addTo('recipient1@example.com'); header.addTo('recipient2@example.com'); // Set unique arguments for email tracking and analytics header.setUniqueArgs({ userId: 'user_xyz_123', transactionType: 'order_confirmation', orderId: 'ORD-2026-04-15-A' }); // Add categories to categorize emails in SendGrid's analytics header.addCategory('Transactional'); header.addCategory('UserNotifications'); // Set substitutions for personalized content in the email body (mail merge) // Placeholder values (e.g., -name-, -item-) will be replaced per recipient. header.setSubstitutions( '-name-', ['Alice Smith', 'Bob Johnson'] ); header.setSubstitutions( '-item-', ['Product A', 'Service B'] ); // Optionally set filters to enable or disable SendGrid App features // This example enables click tracking for these emails. header.setFilter('clicktrack', 'enable', 1); console.log('Generated X-SMTPAPI Header JSON string:'); const xSmtpapiHeader = header.jsonString(); console.log(xSmtpapiHeader); // --- Conceptual usage with an SMTP client (e.g., Nodemailer) --- // Note: This part is for context and requires a separate SMTP transport setup. /* const nodemailer = require('nodemailer'); async function sendEmailWithSmtpapi() { // Ensure your SENDGRID_USERNAME and SENDGRID_PASSWORD environment variables are set const transporter = nodemailer.createTransport({ host: 'smtp.sendgrid.net', port: 587, secure: false, // Use TLS implicitly via STARTTLS auth: { user: process.env.SENDGRID_USERNAME ?? 'YOUR_SENDGRID_USERNAME', pass: process.env.SENDGRID_PASSWORD ?? 'YOUR_SENDGRID_PASSWORD' } }); const mailOptions = { from: 'sender@yourdomain.com', // 'to' field here is often a placeholder; actual recipients are in X-SMTPAPI to: 'placeholder@example.com', subject: 'Your Order Confirmation for -item-, -name-!', text: 'Hello -name-! Your order for -item- has been confirmed.', html: '<b>Hello -name-!</b> Your order for <i>-item-</i> has been confirmed.', headers: { 'X-SMTPAPI': xSmtpapiHeader } }; try { let info = await transporter.sendMail(mailOptions); console.log('Message sent: %s', info.messageId); } catch (error) { console.error('Error sending email:', error); } } sendEmailWithSmtpapi(); */
Debug
Known issues
gotchaThis library is designed to generate X-SMTPAPI headers, which are primarily used with SendGrid's SMTP API and older V2 Mail Send API. For modern integrations using SendGrid's V3 Mail Send API, advanced features (like custom arguments, categories, etc.) are typically passed directly in the JSON payload of the API request, not via X-SMTPAPI headers. Using this library with direct V3 API calls might lead to parameters being ignored or unexpected behavior.
fix
For new projects or integrations with SendGrid's V3 Mail Send API, consult the official `@sendgrid/mail` Node.js SDK documentation for how to pass `custom_args`, `categories`, and other parameters directly in the mail send request body. Only use this library when explicitly sending email via SendGrid's SMTP endpoint or V2 Mail Send API.
affects: >=1.0.0
gotchaThe `smtpapi` library is distributed as a CommonJS (CJS) module. Directly importing it using ES module (ESM) syntax (e.g., `import Smtpapi from 'smtpapi';`) in a Node.js project configured for ESM will result in a `ReferenceError`.
fix
Ensure your project is configured for CommonJS if you wish to use `require()`. If you must use it within an ESM project, use dynamic `import()`: `const SmtpapiModule = await import('smtpapi'); const Smtpapi = SmtpapiModule.default;`.
affects: >=1.0.0
gotchaThe project lists official support for Node.js versions ranging from 4 up to 16. Developing or deploying with extremely old Node.js versions (e.g., 4, 6, 8, 10) is highly discouraged due to known security vulnerabilities, lack of long-term support, and absence of modern JavaScript features. While the library itself is simple, running it on an outdated runtime poses risks.
fix
Always use a currently supported Node.js Long Term Support (LTS) release for development and production environments. While this library is likely compatible with newer Node.js versions due to its simplicity, it's not officially stated to support them beyond v16.
affects: >=1.0.0
Errors
Common errors & fixes
ReferenceError: require is not defined in ES module scope
Attempting to use `require()` to import `smtpapi` within a JavaScript file that Node.js interprets as an ES module (e.g., due to `"type": "module"` in `package.json` or a `.mjs` file extension).
fix
If your project is ESM, either convert the file using `smtpapi` to CommonJS (e.g., change extension to `.cjs` or remove `"type": "module"` from `package.json`), or use dynamic `import()`: `const SmtpapiModule = await import('smtpapi'); const Smtpapi = SmtpapiModule.default;`.
TypeError: Smtpapi is not a constructor
The `smtpapi` export is a class/constructor. This error occurs if you try to call it as a regular function (e.g., `Smtpapi()`) instead of instantiating it with `new` (e.g., `new Smtpapi()`), or if it's incorrectly imported in an ESM context.
fix
Always instantiate the `Smtpapi` object with `new`: `const header = new Smtpapi();`. If using dynamic `import()` in an ESM context, remember to access the default export: `const SmtpapiModule = await import('smtpapi'); const Smtpapi = SmtpapiModule.default; const header = new Smtpapi();`.
Error: Data must be a string. Unique arguments only accept string values.
Methods like `setUniqueArgs()` expect all values in the provided object to be strings, as per the X-SMTPAPI specification.
fix
Ensure all values passed to `setUniqueArgs()` (and similar methods that operate on JSON fields within X-SMTPAPI) are explicitly converted to strings. For example, `{ id: 123 }` should be `{ id: '123' }`.
Upgrade
Version history
0.4.12latest on npm
Audit
Dependencies

No dependency data recorded yet.

Agent activity
15 hits · last 30 days
node
14
OpenAI (training)
1
Resources
githubhttps://github.com/sendgrid/smtpapi-nodejs ↗
packagehttps://www.npmjs.com/package/smtpapi ↗
homepagehttps://sendgrid.com ↗
smtpapi — npm install smtpapi · libregistry