SMTP

Nodemailer

Use Nodemailer to send email through the Lettermint SMTP relay from Node.js.

This guide covers SMTP integration. For full configuration options and available headers, see the SMTP Introduction.

Installation

Install nodemailer via your package manager:

npm install nodemailer

Basic configuration

Use environment variables for credentials:

Code
const SMTP_HOST = 'smtp.lettermint.co';
const SMTP_USERNAME = 'lettermint';
const API_TOKEN = process.env.LETTERMINT_PROJECT_TOKEN;

const nodemailer = require('nodemailer');

const transporter = nodemailer.createTransport({
  host: 'smtp.lettermint.co',
  port: 587,
  secure: false, // STARTTLS
  auth: {
    user: 'lettermint',
    pass: process.env.LETTERMINT_PROJECT_TOKEN,
  },
});

async function sendEmail() {
  try {
    const info = await transporter.sendMail({
      from: 'sender@yourdomain.com',
      to: 'recipient@example.com',
      subject: 'Test Email',
      text: 'Hello! This is a test email.',
      html: '<h1>Hello!</h1><p>This is a test email.</p>',
    });

    console.log('Message sent:', info.messageId);
  } catch (error) {
    console.error('Error sending email:', error);
  }
}

sendEmail();

Advanced features

Multiple recipients

Code
const mailOptions = {
  from: 'sender@yourdomain.com',
  to: ['user1@example.com', 'user2@example.com'],
  cc: 'manager@yourdomain.com',
  bcc: 'archive@yourdomain.com',
  subject: 'Newsletter',
  html: '<h1>Monthly Update</h1>',
};

Attachments

Code
const mailOptions = {
  from: 'sender@yourdomain.com',
  to: 'recipient@example.com',
  subject: 'Document Attached',
  html: '<p>Please find the document attached.</p>',
  attachments: [
    {
      filename: 'document.pdf',
      path: './files/document.pdf',
    },
    {
      filename: 'data.json',
      content: JSON.stringify({ key: 'value' }),
    },
  ],
};

Custom headers

Code
const mailOptions = {
  from: 'sender@yourdomain.com',
  to: 'recipient@example.com',
  subject: 'Custom Headers',
  html: '<p>Email with custom headers.</p>',
  headers: {
    'X-Priority': '1',
    'X-Custom-Header': 'Custom Value',
  },
};

Metadata for tracking

Add metadata that will be included in webhook payloads:

Code
const mailOptions = {
  from: 'sender@yourdomain.com',
  to: 'recipient@example.com',
  subject: 'Order Confirmation',
  html: '<p>Your order has been confirmed.</p>',
  headers: {
    'X-LM-Metadata-order_id': '12345',
    'X-LM-Metadata-customer_id': 'cust_789',
    'X-LM-Metadata-campaign': 'order_confirmation',
  },
};

Lettermint headers

Add Lettermint-specific headers for tags, metadata, and routing:

Code
const mailOptions = {
  from: 'sender@yourdomain.com',
  to: 'recipient@example.com',
  subject: 'Order Confirmation',
  html: '<p>Your order has been confirmed.</p>',
  headers: [
    // Existing singular tag
    { key: 'X-LM-Tag', value: 'order-confirmation' },
    // Structured tags. Nodemailer supports repeated custom headers.
    { key: 'X-LM-Tags', value: 'campaign=orders, environment=production' },
    { key: 'X-LM-Tags', value: 'variant=B' },
    // Metadata for tracking (included in webhooks)
    { key: 'X-LM-Metadata-order_id', value: '12345' },
    { key: 'X-LM-Metadata-customer_id', value: 'cust_789' },
    // Route selection
    { key: 'X-Lettermint-Route', value: 'transactional' },
  ],
};

X-LM-Tag is the singular tag. X-LM-Tags contains structured pairs. Nodemailer writes each array item as a separate custom header.

Metadata headers are extracted by Lettermint and included in webhook payloads, but not added to the actual email sent to recipients. See the SMTP Introduction for full details on available headers.

Response codes PHPMailer