{"library":"smtpapi","title":"SendGrid X-SMTPAPI Headers for Node.js","type":"library","description":"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.","language":"javascript","status":"maintenance","last_verified":"Sun Apr 19","install":{"commands":["npm install smtpapi"],"cli":null},"imports":["const Smtpapi = require('smtpapi');","const header = new Smtpapi();","const headerString = header.jsonString();"],"auth":{"required":false,"env_vars":[]},"links":{"homepage":"https://sendgrid.com","github":"https://github.com/sendgrid/smtpapi-nodejs","docs":null,"changelog":null,"pypi":null,"npm":"https://www.npmjs.com/package/smtpapi","openapi_spec":null,"status_page":null,"smithery":null},"quickstart":{"code":"const Smtpapi = require('smtpapi');\n\n// Create a new SMTPAPI header instance\nconst header = new Smtpapi();\n\n// Add multiple recipients to the 'to' field\nheader.addTo('recipient1@example.com');\nheader.addTo('recipient2@example.com');\n\n// Set unique arguments for email tracking and analytics\nheader.setUniqueArgs({\n  userId: 'user_xyz_123',\n  transactionType: 'order_confirmation',\n  orderId: 'ORD-2026-04-15-A'\n});\n\n// Add categories to categorize emails in SendGrid's analytics\nheader.addCategory('Transactional');\nheader.addCategory('UserNotifications');\n\n// Set substitutions for personalized content in the email body (mail merge)\n// Placeholder values (e.g., -name-, -item-) will be replaced per recipient.\nheader.setSubstitutions(\n  '-name-', ['Alice Smith', 'Bob Johnson']\n);\nheader.setSubstitutions(\n  '-item-', ['Product A', 'Service B']\n);\n\n// Optionally set filters to enable or disable SendGrid App features\n// This example enables click tracking for these emails.\nheader.setFilter('clicktrack', 'enable', 1);\n\nconsole.log('Generated X-SMTPAPI Header JSON string:');\nconst xSmtpapiHeader = header.jsonString();\nconsole.log(xSmtpapiHeader);\n\n// --- Conceptual usage with an SMTP client (e.g., Nodemailer) --- \n// Note: This part is for context and requires a separate SMTP transport setup.\n/*\nconst nodemailer = require('nodemailer');\n\nasync function sendEmailWithSmtpapi() {\n  // Ensure your SENDGRID_USERNAME and SENDGRID_PASSWORD environment variables are set\n  const transporter = nodemailer.createTransport({\n    host: 'smtp.sendgrid.net',\n    port: 587,\n    secure: false, // Use TLS implicitly via STARTTLS\n    auth: {\n      user: process.env.SENDGRID_USERNAME ?? 'YOUR_SENDGRID_USERNAME',\n      pass: process.env.SENDGRID_PASSWORD ?? 'YOUR_SENDGRID_PASSWORD'\n    }\n  });\n\n  const mailOptions = {\n    from: 'sender@yourdomain.com',\n    // 'to' field here is often a placeholder; actual recipients are in X-SMTPAPI\n    to: 'placeholder@example.com', \n    subject: 'Your Order Confirmation for -item-, -name-!',\n    text: 'Hello -name-! Your order for -item- has been confirmed.',\n    html: '<b>Hello -name-!</b> Your order for <i>-item-</i> has been confirmed.',\n    headers: {\n      'X-SMTPAPI': xSmtpapiHeader\n    }\n  };\n\n  try {\n    let info = await transporter.sendMail(mailOptions);\n    console.log('Message sent: %s', info.messageId);\n  } catch (error) {\n    console.error('Error sending email:', error);\n  }\n}\n\nsendEmailWithSmtpapi();\n*/","lang":"javascript","description":"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.","tag":null,"tag_description":null,"last_tested":null,"results":[]},"compatibility":null}