📧 Mail Service Drivers

Mail service drivers provide a consistent interface for sending emails in NodeBlocks applications. They abstract email provider configuration and the sendMail contract used by SDK services.

---

🎯 Overview

Mail service drivers in NodeBlocks are factory functions that create configured SendGrid mail service instances. The SDK ships one SendGrid driver today. Custom providers can implement the MailService interface from src/types/email.ts and be injected the same way.

import { drivers } from '@nodeblocks/backend-sdk';

const { getSendGridClient, setBaseUrl } = drivers;

---

📋 Available Mail Service Drivers

SendGrid Driver

The SendGrid driver creates a configured SendGrid mail service for sending emails through the SendGrid API.

getSendGridClient

Creates a SendGrid mail service client with API key and optional base URL configuration. This is a synchronous factory — no await is required.

Parameters:

Parameter	Type	Description
apiKey	string	SendGrid API key for authentication
baseUrl?	string	Optional base URL for SendGrid API (useful for testing/staging)

Returns: MailService — Configured mail service with sendMail method

Global side effects: getSendGridClient calls mail.setApiKey(apiKey) on the shared @sendgrid/mail singleton — repeated calls or multiple API keys affect all SendGrid operations in the process. When baseUrl is provided, it also calls setBaseUrl internally — the same singleton mutation as calling setBaseUrl directly.

Usage:

import { drivers } from '@nodeblocks/backend-sdk';

const { getSendGridClient } = drivers;

const mailService = getSendGridClient(process.env.SENDGRID_API_KEY!);

const success = await mailService.sendMail({
  to: 'user@example.com',
  from: 'noreply@company.com',
  subject: 'Welcome!',
  text: 'Welcome to our platform',
});
// Returns true when SendGrid responds with status code 202

Example with Custom Base URL:

import { drivers } from '@nodeblocks/backend-sdk';

const { getSendGridClient } = drivers;

const mailService = getSendGridClient(
  process.env.SENDGRID_API_KEY!,
  'https://api.sendgrid.com/v3'
);

Error behavior:

Outcome	Behavior
HTTP 202	Returns true
Other HTTP status	Returns false
SendGrid API failure	Throws — errors from mail.send() propagate; they are not swallowed into false

Note: The shared MailService type allows an optional second opts argument (MailOptions), but getSendGridClient currently implements sendMail(mailData) only — it does not pass logger or sandboxMode to SendGrid.

SendGridMail

Exported type from SDK source (src/drivers/sendgrid.ts) for the underlying SendGrid client:

type SendGridMail = typeof mail & {
  client: Parameters<typeof mail.setClient>[0];
};

This type is primarily useful when configuring or testing the shared SendGrid client directly. Most applications should use the MailService returned by getSendGridClient.

setBaseUrl

Sets the base URL for SendGrid API requests to enable custom endpoints or testing.

Global side effect: setBaseUrl mutates the shared @sendgrid/mail singleton via mail.client.setDefaultRequest('baseUrl', baseUrl). It affects all subsequent SendGrid operations in the process, not just a single client instance returned by getSendGridClient.

Parameters:

Parameter	Type	Description
baseUrl	string	Base URL for SendGrid API requests (e.g. 'https://api.sendgrid.com/v3')

Returns: void

Usage:

import { drivers } from '@nodeblocks/backend-sdk';

const { setBaseUrl } = drivers;

setBaseUrl('https://api.sendgrid.com/v3');
setBaseUrl('https://api-staging.sendgrid.com/v3'); // testing/staging

---

📧 Mail Types

Shared mail types live under the types namespace (SDK source: src/types/email.ts):

import { types } from '@nodeblocks/backend-sdk';

type MailData = types.MailData;
type MailService = types.MailService;
type MailOptions = types.MailOptions;

MailData rules (passed to sendMail):

Rule	Detail
Required fields	from, subject, to
Content	At least one of html or text is required; the TypeScript union does not prohibit providing both
Recipients	Single recipient per email
Attachments	Not supported by the MailData type

const email: MailData = {
  to: 'user@example.com',
  from: 'noreply@company.com',
  subject: 'Welcome!',
  text: 'Welcome to our platform',
};

See src/types/email.ts for full MailData, MailService, and MailOptions definitions. MailOptions (logger, sandboxMode) exists on the shared MailService interface but is not used by getSendGridClient today.

---

🔧 Using Mail Service Drivers

With Services

Inject the driver via the third-argument options on authService:

import { services, drivers } from '@nodeblocks/backend-sdk';

const { authService } = services;
const { getSendGridClient } = drivers;

const mailService = getSendGridClient(process.env.SENDGRID_API_KEY!);

authService(
  dataStores,
  {
    authSecrets: {
      authEncSecret: process.env.AUTH_ENC_SECRET!,
      authSignSecret: process.env.AUTH_SIGN_SECRET!,
    },
  },
  { mailService }
);

See Authentication Service for full Express wiring, data stores (identities, refreshtokens, optional onetimetokens and invitations), OAuth drivers, and email verification configuration.

---

🔗 Related Documentation

• Drivers Overview — Full drivers export inventory
• Authentication Service — Service that accepts a mailService dependency