@memberjunction/communication-engine

Server-side communication engine for MemberJunction. This package extends CommunicationEngineBase from @memberjunction/communication-types to provide the concrete implementation for sending messages, creating drafts, and managing communication runs through registered providers.

Architecture

graph TD
    subgraph engine["@memberjunction/communication-engine"]
        CE["CommunicationEngine\n(Singleton)"]
        PMS["ProcessedMessageServer"]
    end

    subgraph base["@memberjunction/communication-types"]
        CEB["CommunicationEngineBase"]
        BCP["BaseCommunicationProvider"]
        MSG["Message"]
    end

    subgraph providers["Registered Providers"]
        SG["SendGrid"]
        GM["Gmail"]
        TW["Twilio"]
        MSP["MS Graph"]
    end

    subgraph templates["@memberjunction/templates"]
        TE["TemplateEngineServer"]
    end

    CEB --> CE
    CE -->|GetProvider| BCP
    CE -->|processes| MSG
    MSG --> PMS
    PMS -->|renders via| TE
    BCP --> SG
    BCP --> GM
    BCP --> TW
    BCP --> MSP

    style engine fill:#7c5295,stroke:#563a6b,color:#fff
    style base fill:#2d6a9f,stroke:#1a4971,color:#fff
    style providers fill:#2d8659,stroke:#1a5c3a,color:#fff
    style templates fill:#b8762f,stroke:#8a5722,color:#fff
Copy

Installation

npm install @memberjunction/communication-engine
Copy

Key Classes

CommunicationEngine

Singleton engine that orchestrates message sending across all registered providers. Handles provider lookup via the MJGlobal class factory, message processing (template rendering), communication run lifecycle, and logging.

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

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

Sending a Single Message

const message = new Message();
message.From = 'sender@example.com';
message.To = 'recipient@example.com';
message.Subject = 'Welcome';
message.HTMLBody = '<h1>Hello</h1>';

const result = await engine.SendSingleMessage(
    'SendGrid',           // provider name
    'Email',              // provider message type name
    message,
    undefined,            // optional CommunicationRunEntity
    false                 // previewOnly
);

if (result.Success) {
    console.log('Message sent');
}
Copy

Sending to Multiple Recipients

const recipients: MessageRecipient[] = [
    { To: 'alice@example.com', FullName: 'Alice', ContextData: { role: 'admin' } },
    { To: 'bob@example.com', FullName: 'Bob', ContextData: { role: 'user' } }
];

const message = new Message();
message.From = 'noreply@example.com';
message.BodyTemplate = templateEntity; // uses template for personalization
message.Subject = 'Update';

const results = await engine.SendMessages(
    'SendGrid',
    'Email',
    message,
    recipients,
    false // previewOnly
);
// results is MessageResult[] - one per recipient
Copy

Creating a Draft

const message = new Message();
message.From = 'user@example.com';
message.To = 'recipient@example.com';
message.Subject = 'Draft Email';
message.HTMLBody = '<p>Content here</p>';

const result = await engine.CreateDraft(
    message,
    'Microsoft Graph', // only providers with SupportsDrafts
    contextUser
);

if (result.Success) {
    console.log(`Draft ID: ${result.DraftID}`);
}
Copy

Per-Request Credentials

All send methods accept an optional credentials parameter for per-request credential overrides:

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

const result = await engine.SendSingleMessage(
    'SendGrid',
    'Email',
    message,
    undefined,
    false,
    { apiKey: 'SG.customer-specific-key' } // per-request credentials
);
Copy

ProcessedMessageServer

Server-side implementation of ProcessedMessage that renders templates using TemplateEngineServer. Automatically processes body, HTML body, and subject templates with the provided context data.

sequenceDiagram
    participant App as Application
    participant CE as CommunicationEngine
    participant PMS as ProcessedMessageServer
    participant TE as TemplateEngineServer
    participant P as Provider

    App->>CE: SendSingleMessage(providerName, messageType, message)
    CE->>CE: GetProvider(providerName)
    CE->>PMS: new ProcessedMessageServer(message)
    CE->>PMS: Process()
    PMS->>TE: RenderTemplate(bodyTemplate, contextData)
    TE-->>PMS: rendered content
    PMS-->>CE: ProcessResult
    CE->>P: SendSingleMessage(processedMessage, credentials)
    P-->>CE: MessageResult
    CE-->>App: MessageResult
Copy

API Reference

Dependencies

Development

npm run build    # Compile TypeScript
npm start        # Watch mode
Copy