@gabster/mail-ms

Typed HTTP client SDK for the Gabster mail microservice.

Installation

npm install @gabster/mail-ms

Quick Start

import Mailer from "@gabster/mail-ms";

const mail = new Mailer({
  host: process.env.GABSTER_MAIL_HOST,   // e.g. "https://smail.internal.gbstr.io"
  apiKey: process.env.GABSTER_MAIL_API_KEY,
});

Sending Emails

Raw HTML

const result = await mail.send.raw({
  to: "[email protected]",
  subject: "Welcome aboard",
  html: "<h1>Hello!</h1><p>Welcome to our platform.</p>",
  text: "Hello! Welcome to our platform.",       // optional plain-text fallback
  tags: ["onboarding"],                          // optional tags
  metadata: { userId: "abc123" },                // optional metadata (stored in logs)
});

console.log(result);
// { success: true, emailLogId: "664f...", messageId: "msg_..." }

Templated (server-side templates)

await mail.send.templated({
  template: "welcome",
  to: "[email protected]",
  subject: "You're invited!",                    // optional (uses template default)
  variables: {
    recipientEmail: "[email protected]",
    orgName: "Gabster",
    invitationId: "inv_123",
    link: "https://app.gabster.ai/invite/inv_123",
    isNewUser: true,
  },
});

Available templates: welcome, notification, ticket, otp, expiration, usage-limit, custom.

Dynamic (block-based)

Build emails on the fly using content blocks:

await mail.send.dynamic({
  to: "[email protected]",
  subject: "Your Weekly Report",
  styles: {
    primaryColor: "#2563eb",
    backgroundColor: "#f3f4f6",
    fontFamily: "Arial, sans-serif",
  },
  blocks: [
    { type: "heading", text: "Hello {{name}}", level: 1, align: "center" },
    { type: "text", text: "Here is your weekly summary." },
    { type: "divider" },
    { type: "text", text: "You completed {{tasks}} tasks this week." },
    { type: "button", text: "View Dashboard", link: "https://app.example.com/dashboard" },
    { type: "image", src: "https://cdn.example.com/banner.png", alt: "Banner", width: "100%" },
  ],
  variables: { name: "John", tasks: "12" },      // replaces {{name}}, {{tasks}} in blocks
});

Block types:

| Type | Required fields | Optional fields | |-------------|----------------------|--------------------------------------| | heading | text | level (1-3), color, align | | text | text | color, align | | button | text, link | color, bgColor, align | | image | src | alt, width, align | | divider | -- | color, thickness |

Email Logs

// Query logs with filters
const logs = await mail.logs.query({
  status: "failed",     // "pending" | "sent" | "failed" | "retrying"
  template: "welcome",  // filter by template name
  to: "[email protected]",
  page: 1,
  limit: 20,
});

console.log(logs.data);       // EmailLog[]
console.log(logs.total);      // total matching records
console.log(logs.totalPages); // total pages

// Get a single log by ID
const log = await mail.logs.getById("664fa1b2c3d4e5f6a7b8c9d0");
console.log(log.data.status); // "sent"

Health Check

const status = await mail.health();

console.log(status);
// {
//   success: true,
//   service: "mail-ms",
//   uptime: 3600.5,
//   mongo: "connected",
//   timestamp: "2026-04-05T23:00:00.000Z"
// }

Configuration

| Parameter | Required | Description | |-----------|----------|------------------------------------------| | host | Yes | Base URL of the mail-ms service | | apiKey | Yes | Per-service API key (from /v1/api-keys)|

Environment Variables

GABSTER_MAIL_HOST=https://smail.internal.gbstr.io
GABSTER_MAIL_API_KEY=gab_mail_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

API Reference

new Mailer(config)

Creates a new client instance.

mail.send.raw(params): Promise<SendResult>

Send an email with raw HTML content.

mail.send.templated(params): Promise<SendResult>

Send an email using a server-side template.

mail.send.dynamic(params): Promise<SendResult>

Send an email built from dynamic content blocks.

mail.logs.query(params?): Promise<PaginatedLogs>

Query email logs with optional filters and pagination.

mail.logs.getById(id): Promise<LogDetailResponse>

Get a single email log entry by its ID.

mail.health(): Promise<HealthStatus>

Check the health of the mail-ms service.

Types

All TypeScript interfaces are exported for full autocomplete:

import Mailer, {
  MailerConfig,
  SendRawParams,
  SendTemplatedParams,
  SendDynamicParams,
  SendResult,
  DynamicBlock,
  DynamicStyles,
  HeadingBlock,
  TextBlock,
  ButtonBlock,
  ImageBlock,
  DividerBlock,
  EmailLog,
  PaginatedLogs,
  LogQueryParams,
  HealthStatus,
  TemplateName,
  EmailStatus,
} from "@gabster/mail-ms";

License

UNLICENSED -- Internal use only.