@memberjunction/communication-sendgrid

SendGrid provider for the MemberJunction Communication Framework. This provider enables transactional email sending through the SendGrid API, with support for HTML and plain text content, CC/BCC recipients, scheduled delivery, and per-request credential overrides.

Architecture

graph TD
    subgraph sendgrid["@memberjunction/communication-sendgrid"]
        SGP["SendGridProvider"]
        CFG["Config Module\n(Environment Variable)"]
        CRED["SendGridCredentials"]
    end

    subgraph sg["SendGrid Service"]
        API["SendGrid Web API v3"]
        DELIVERY["Email Delivery"]
    end

    subgraph base["@memberjunction/communication-types"]
        BCP["BaseCommunicationProvider"]
    end

    BCP --> SGP
    SGP --> CFG
    SGP --> CRED
    SGP --> API
    API --> DELIVERY

    style sendgrid fill:#2d6a9f,stroke:#1a4971,color:#fff
    style sg fill:#7c5295,stroke:#563a6b,color:#fff
    style base fill:#2d8659,stroke:#1a5c3a,color:#fff
Copy

Installation

npm install @memberjunction/communication-sendgrid
Copy

Configuration

Set the following environment variable:

COMMUNICATION_VENDOR_API_KEY__SENDGRID=SG.your-api-key-here
Copy

Supported Operations

SendGrid is a send-only transactional email service. It does not provide mailbox access.

Usage

Sending Email via CommunicationEngine

import { CommunicationEngine } from '@memberjunction/communication-engine';
import { Message } from '@memberjunction/communication-types';

const engine = CommunicationEngine.Instance;
await engine.Config(false, contextUser);

const message = new Message();
message.From = 'noreply@example.com';
message.FromName = 'My Application';
message.To = 'recipient@example.com';
message.Subject = 'Order Confirmation';
message.HTMLBody = '<h1>Thank you for your order</h1>';
message.Body = 'Thank you for your order';
message.CCRecipients = ['accounting@example.com'];

const result = await engine.SendSingleMessage('SendGrid', 'Email', message);
if (result.Success) {
    console.log('Email sent successfully');
}
Copy

Scheduled Sending

const message = new Message();
message.From = 'noreply@example.com';
message.To = 'recipient@example.com';
message.Subject = 'Scheduled Report';
message.Body = 'Your weekly report is attached.';
message.SendAt = new Date('2025-12-01T09:00:00Z');

const result = await engine.SendSingleMessage('SendGrid', 'Email', message);
Copy

Per-Request Credentials

Override the API key for multi-tenant or customer-specific sending:

import { SendGridCredentials } from '@memberjunction/communication-sendgrid';

// Override API key
const result = await engine.SendSingleMessage(
    'SendGrid',
    'Email',
    message,
    undefined,
    false,
    { apiKey: 'SG.customer-specific-api-key' } as SendGridCredentials
);

// Disable environment fallback (require explicit key)
const result2 = await engine.SendSingleMessage(
    'SendGrid',
    'Email',
    message,
    undefined,
    false,
    {
        apiKey: 'SG.required-key',
        disableEnvironmentFallback: true
    } as SendGridCredentials
);
Copy

Direct Provider Usage

import { SendGridProvider } from '@memberjunction/communication-sendgrid';

const provider = new SendGridProvider();
const result = await provider.SendSingleMessage(processedMessage);
Copy

Message Features

SendGridCredentials

interface SendGridCredentials extends ProviderCredentialsBase {
    /** SendGrid API key (typically starts with 'SG.') */
    apiKey?: string;
    /** If true, do not fall back to environment variables */
    disableEnvironmentFallback?: boolean;
}
Copy

Dependencies

Development

npm run build    # Compile TypeScript
npm run clean    # Remove dist directory
Copy