tessl/npm-sendgrid--mail

Twilio SendGrid NodeJS mail service for sending transactional and marketing emails with templates, attachments, and advanced delivery features.

—

Pending

Overview

Eval results

Files

Advanced Delivery

Name: tessl/npm-sendgrid--mail
Author: tessl

Advanced email delivery features including scheduling, batching, IP pools, suppression management, and mail settings for optimized email delivery control.

Capabilities

Scheduled Delivery

Schedule emails to be sent at a specific future time using Unix timestamps.

/**
 * Schedule email delivery for a specific time
 * @param sendAt - Unix timestamp for when to send the email
 */
const msg = {
  to: 'recipient@example.com',
  from: 'sender@example.com',
  subject: 'Scheduled Email',
  text: 'This email was scheduled for later delivery',
  sendAt: 1640995200  // Unix timestamp (e.g., January 1, 2022)
};

Usage Example:

const sgMail = require('@sendgrid/mail');

// Schedule email for specific date/time
const futureDate = new Date('2024-12-25T10:00:00Z');
const sendAtTimestamp = Math.floor(futureDate.getTime() / 1000);

const scheduledMsg = {
  to: 'recipient@example.com',
  from: 'sender@example.com', 
  subject: 'Merry Christmas!',
  html: '<h1>Season\'s Greetings!</h1>',
  sendAt: sendAtTimestamp
};

sgMail.send(scheduledMsg);

Batch Management

Group related emails together using batch IDs for tracking and management purposes.

/**
 * Group emails using batch identifiers
 * @param batchId - Unique identifier for grouping related emails
 */
const msg = {
  to: 'recipient@example.com',
  from: 'sender@example.com',
  subject: 'Batch Email',
  text: 'Part of email batch',
  batchId: 'newsletter-2024-01'  // Custom batch identifier
};

Usage Example:

const sgMail = require('@sendgrid/mail');

const batchId = 'campaign-' + Date.now();

// Send multiple emails with same batch ID
const emails = [
  {
    to: 'user1@example.com',
    from: 'newsletter@company.com',
    subject: 'Weekly Newsletter',
    html: '<h2>Newsletter Content</h2>',
    batchId: batchId
  },
  {
    to: 'user2@example.com', 
    from: 'newsletter@company.com',
    subject: 'Weekly Newsletter',
    html: '<h2>Newsletter Content</h2>',
    batchId: batchId
  }
];

// All emails will share the same batch ID for tracking
sgMail.send(emails);

IP Pool Management

Control which IP pool is used for sending emails, useful for reputation management and delivery optimization.

/**
 * Specify IP pool for email delivery
 * @param ipPoolName - Name of the IP pool to use for sending
 */
const msg = {
  to: 'recipient@example.com',
  from: 'sender@example.com',
  subject: 'Email via IP Pool',
  text: 'Sent using dedicated IP pool',
  ipPoolName: 'marketing_pool'  // Specific IP pool name
};

Usage Example:

const sgMail = require('@sendgrid/mail');

// Send transactional email via dedicated IP pool
const transactionalMsg = {
  to: 'customer@example.com',
  from: 'orders@company.com',
  subject: 'Order Confirmation',
  html: '<h2>Your order has been confirmed</h2>',
  ipPoolName: 'transactional_pool'
};

// Send marketing email via different IP pool
const marketingMsg = {
  to: 'subscriber@example.com',
  from: 'marketing@company.com', 
  subject: 'Special Offer',
  html: '<h2>Limited Time Offer!</h2>',
  ipPoolName: 'marketing_pool'
};

sgMail.send([transactionalMsg, marketingMsg]);

Advanced Suppression Management (ASM)

Control unsubscribe group settings and suppression management for compliance and subscriber management.

/**
 * Configure Advanced Suppression Management settings
 * @param asm - ASM configuration object
 */
interface ASMOptions {
  groupId: number;           // Unsubscribe group ID
  groupsToDisplay?: number[]; // Additional groups to display in unsubscribe
}

const msg = {
  to: 'recipient@example.com',
  from: 'sender@example.com',
  subject: 'Email with ASM',
  text: 'Email with suppression management',
  asm: {
    groupId: 123,              // Primary unsubscribe group
    groupsToDisplay: [124, 125] // Additional groups to show
  }
};

Usage Example:

const sgMail = require('@sendgrid/mail');

// Marketing email with proper ASM settings
const marketingEmail = {
  to: 'subscriber@example.com',
  from: 'marketing@company.com',
  subject: 'Weekly Promotions',
  html: '<h2>This Week\'s Deals</h2><p>Great offers await!</p>',
  asm: {
    groupId: 100,  // Marketing emails unsubscribe group
    groupsToDisplay: [100, 101, 102]  // Show marketing, weekly, and promotional options
  }
};

sgMail.send(marketingEmail);

Categories and Custom Arguments

Add metadata for tracking and organization purposes.

/**
 * Add categories and custom arguments for tracking
 * @param categories - Array of category strings for email classification
 * @param customArgs - Custom key-value pairs for additional metadata
 */
const msg = {
  to: 'recipient@example.com',
  from: 'sender@example.com',
  subject: 'Categorized Email',
  text: 'Email with categories and custom args',
  categories: ['Newsletter', 'Marketing', 'Q1-2024'],
  customArgs: {
    campaignId: 'spring-2024',
    userId: '12345',
    department: 'marketing'
  }
};

Usage Example:

const sgMail = require('@sendgrid/mail');

// Email with comprehensive tracking metadata
const trackedEmail = {
  to: 'customer@example.com',
  from: 'support@company.com',
  subject: 'Account Update',
  html: '<h2>Your account has been updated</h2>',
  categories: ['Account', 'Transactional', 'Updates'],
  customArgs: {
    userId: 'user_67890',
    accountType: 'premium',
    updateType: 'profile',
    triggeredBy: 'user_action'
  }
};

sgMail.send(trackedEmail);

Mail Settings

Configure email behavior settings including spam checking, sandboxing, and footer management.

/**
 * Configure mail behavior settings
 */
interface MailSettings {
  sandboxMode?: { enable?: boolean };
  spamCheck?: { enable?: boolean; threshold?: number; postToUrl?: string };
  bypassListManagement?: { enable?: boolean };
  footer?: { enable?: boolean; text?: string; html?: string };
}

const msg = {
  to: 'recipient@example.com',
  from: 'sender@example.com',
  subject: 'Email with Mail Settings',
  text: 'Email with custom mail settings',
  mailSettings: {
    sandboxMode: { enable: false },
    spamCheck: { 
      enable: true, 
      threshold: 3,
      postToUrl: 'https://example.com/spam-report'
    },
    footer: {
      enable: true,
      text: 'Sent by Company Name',
      html: '<p><em>Sent by Company Name</em></p>'
    }
  }
};

Complete Advanced Delivery Example

const sgMail = require('@sendgrid/mail');

// Comprehensive advanced delivery configuration
const advancedMsg = {
  to: 'recipient@example.com',
  from: 'sender@company.com',
  subject: 'Advanced Delivery Email',
  html: '<h2>Important Update</h2><p>This email uses advanced delivery features.</p>',
  
  // Scheduling
  sendAt: Math.floor(Date.now() / 1000) + 3600, // Send in 1 hour
  
  // Batch management
  batchId: 'quarterly-update-2024-q1',
  
  // IP pool selection
  ipPoolName: 'premium_delivery',
  
  // Suppression management
  asm: {
    groupId: 200,
    groupsToDisplay: [200, 201, 202]
  },
  
  // Tracking and categorization
  categories: ['Updates', 'Quarterly', 'Important'],
  customArgs: {
    quarter: 'Q1-2024',
    department: 'operations',
    priority: 'high'
  },
  
  // Mail behavior settings
  mailSettings: {
    sandboxMode: { enable: false },
    spamCheck: { enable: true, threshold: 5 },
    footer: {
      enable: true,
      text: '\n\nCompany Name | Unsubscribe | Privacy Policy',
      html: '<hr><p><small>Company Name | <a href="#">Unsubscribe</a> | <a href="#">Privacy Policy</a></small></p>'
    }
  }
};

sgMail.send(advancedMsg)
  .then(() => console.log('Advanced email scheduled successfully'))
  .catch(error => console.error('Error:', error));

Types

// Advanced Suppression Management options
interface ASMOptions {
  groupId: number;              // Primary unsubscribe group ID
  groupsToDisplay?: number[];   // Additional unsubscribe groups to display
}

// Mail settings configuration
interface MailSettings {
  sandboxMode?: { enable?: boolean };
  spamCheck?: { 
    enable?: boolean; 
    threshold?: number; 
    postToUrl?: string; 
  };
  bypassListManagement?: { enable?: boolean };
  footer?: { 
    enable?: boolean; 
    text?: string; 
    html?: string; 
  };
}

// Advanced delivery data structure
interface AdvancedDeliveryData {
  sendAt?: number;              // Unix timestamp for scheduled delivery
  batchId?: string;            // Batch identifier for grouping
  ipPoolName?: string;         // IP pool name for sending
  asm?: ASMOptions;            // Advanced Suppression Management
  categories?: string[];        // Email categories for tracking
  customArgs?: { [key: string]: any }; // Custom tracking arguments
  mailSettings?: MailSettings;  // Email behavior settings
}

Install with Tessl CLI