ul-email-platform

Official Node.js / TypeScript SDK for the Email Platform API.

Installation

npm install ul-email-platform

Quick Start

import { EmailPlatformClient } from 'ul-email-platform';

// CommonJS
const { EmailPlatformClient } = require('ul-email-platform');

const client = new EmailPlatformClient({
  apiKey: 'ep_live_your_api_key',
  baseUrl: 'http://localhost:3000', // Optional: defaults to localhost
  platform: 'YOUR_PLATFORM',
});

Sending Emails

Raw HTML Email

const result = await client.emails.send({
  to: { email: '[email protected]', name: 'Alice' },
  subject: 'Hello!',
  html: '<h1>Hi Alice</h1>',
  from: { email: '[email protected]', name: 'My App' },
  replyTo: '[email protected]',
});

console.log(result.messageId); // ep_01j...

CC and BCC

await client.emails.send({
  to: { email: '[email protected]' },
  cc: [{ email: '[email protected]' }],
  bcc: [{ email: '[email protected]' }],
  subject: 'Invoice',
  html: '<p>See attached.</p>',
});

Attachments

import fs from 'fs';

await client.emails.send({
  to: { email: '[email protected]' },
  subject: 'Your report',
  html: '<p>Report attached.</p>',
  attachments: [
    {
      filename: 'report.pdf',
      content: fs.readFileSync('report.pdf').toString('base64'),
      contentType: 'application/pdf',
      size: fs.statSync('report.pdf').size,
    },
  ],
});

Template Email with Variables

await client.emails.sendTemplate({
  to: { email: '[email protected]' },
  templateId: 'welcome-email', // Template slug registered in the platform
  templateStatus: 'DRAFT', // DRAFT | PUBLISHED
  variables: {
    name: 'Alice',
    activationLink: 'https://myapp.com/activate?token=abc',
  },
  tags: ['welcome'],
  idempotencyKey: 'welcome-alice-001',
});

Email Status & History

const status = await client.emails.getStatus('ep_01j...');

console.log(status.status); // SENT | DELIVERED | OPENED ...
console.log(status.openCount);
console.log(status.events); // Full event timeline

Get All Emails for a Recipient

const data = await client.emails.getEmails('[email protected]');

console.log(data);

Resend an Email

const resent = await client.emails.resend('ep_01j...');

All Send Options

| Option | Type | Description | | ---------------- | ----------------------------------------- | ------------------------------------- | | to | EmailAddress \| EmailAddress[] | Recipients | | cc | EmailAddress \| EmailAddress[] | CC recipients | | bcc | EmailAddress \| EmailAddress[] | BCC recipients | | from | EmailAddress | Sender (defaults to tenant default) | | replyTo | string | Reply-to address | | subject | string | Email subject (raw send) | | redacted | boolean | Whether the email content is redacted | | html | string | HTML body (raw send) | | templateId | string | Template slug (template send) | | templateStatus | PUBLISHED \| DRAFT | Defaults to PUBLISHED | | variables | Record<string, unknown> | Template variables | | attachments | Attachment[] | File attachments (base64 encoded) | | priority | HIGH \| NORMAL \| LOW \| BULK | Queue priority | | emailType | TRANSACTIONAL \| MARKETING \| SYSTEM | Email classification | | tags | string[] | Up to 10 tags for filtering | | scheduleAt | Date \| string | Future send time (ISO 8601) | | idempotencyKey | string | Deduplication key (24h window) |