fastify-xemail

SendGrid email plugin for Fastify — transactional emails, dynamic templates, bulk sending, address validation, and marketing contact management.

fastify-xemail

SendGrid integration for Fastify v5. Decorate your server with fastify.xEmail and send transactional emails, dynamic template emails, bulk messages, file attachments, and personalized per-recipient emails — plus validate addresses and manage marketing contacts and lists.

Installation

npm install @xenterprises/fastify-xemail

Quick Start

import Fastify from "fastify";
import xEmail from "@xenterprises/fastify-xemail";

const fastify = Fastify();

await fastify.register(xEmail, {
  apiKey: process.env.SENDGRID_API_KEY,
  fromEmail: process.env.SENDGRID_FROM_EMAIL,
  fromName: "My App",
});

fastify.post("/welcome", async (request) => {
  return fastify.xEmail.send(
    request.body.email,
    "Welcome!",
    "<h1>Welcome!</h1><p>Thanks for signing up.</p>"
  );
});

await fastify.listen({ port: 3000 });

Options

Name	Type	Default	Required	Description
`apiKey`	`string`	—	Yes	SendGrid API key with Mail Send permissions.
`fromEmail`	`string`	—	Yes	Verified sender email address.
`fromName`	`string`	—	No	Sender display name (combined with `fromEmail` into a `{ email, name }` object).
`active`	`boolean`	`true`	No	Set `false` to skip plugin registration entirely (useful in test environments).

Methods

Sending

send — Send a transactional email with HTML content.
send-template — Send using a SendGrid dynamic template.
send-with-attachments — Send an email with file attachments.
send-bulk — Send the same email to multiple recipients in one API call.
send-personalized-bulk — Send different content to each recipient using Promise.allSettled.

Validation

validate — Validate an email address using the SendGrid Email Validation API.

Contacts

contacts-add — Add or update a contact in SendGrid Marketing.
contacts-search — Search for a marketing contact by email address.
contacts-delete — Delete a marketing contact by ID.

Lists

lists-create — Create a new SendGrid Marketing contact list.
lists-get — Get all contact lists.
lists-delete — Delete a contact list by ID.

Error Reference

Startup Errors

Error	Cause
`[xEmail] 'apiKey' (string) is required.`	Missing or non-string `apiKey` at registration.
`[xEmail] 'fromEmail' (string) is required.`	Missing or non-string `fromEmail` at registration.

Runtime Errors

All runtime errors are thrown with the [xEmail] prefix. See each method page for the specific error messages.

Environment Variables

Variable	Required	Description
`SENDGRID_API_KEY`	Yes	SendGrid API key with Mail Send and Marketing permissions.
`SENDGRID_FROM_EMAIL`	Yes	Verified sender email address.
`SENDGRID_FROM_NAME`	No	Sender display name.

How It Works

The plugin initializes @sendgrid/mail (transactional sending) and @sendgrid/client (Marketing and Validation REST APIs) with the provided API key, then decorates the Fastify instance with fastify.xEmail. Transactional methods (send, sendTemplate, sendWithAttachments, sendBulk, sendPersonalizedBulk) use sgMail; contact management and validation methods use sgClient with direct REST calls. All methods validate required inputs before hitting the API. Errors are caught, logged via fastify.log.error (credentials are never logged), and re-thrown with a [xEmail] prefix. validate() returns a soft error result instead of throwing. Setting active: false skips registration entirely.

AI Context

package: "@xenterprises/fastify-xemail"
type: fastify-plugin
use-when: Transactional email and marketing contact management via SendGrid
decorator: fastify.xEmail
methods: send, sendTemplate, sendWithAttachments, sendBulk, sendPersonalizedBulk, validate, contacts (add/search/delete), lists (create/get/delete)
env: SENDGRID_API_KEY, SENDGRID_FROM_EMAIL, SENDGRID_FROM_NAME (optional)

Edit this pageorReport an issue

stream

Streaming text generation that returns an async-iterable textStream for real-time output.

contacts-add

Add or update a contact in SendGrid Marketing using the upsert API.