Node.js SDK

Send email with Encore

Use Parcel Wing from Encore.ts type-safe API endpoints and store the API key in Encore secrets.

Install the SDK

The official SDK is published as @parcelwing/node.

Terminal

npm install @parcelwing/node

Secrets

Store the Parcel Wing API key as an Encore secret, then read it from trusted backend code.

Terminal

encore secret set --type local ParcelWingApiKey
encore secret set --type dev ParcelWingApiKey
encore secret set --type prod ParcelWingApiKey

API endpoint

Expose a typed Encore API endpoint that sends a saved template and returns the created message ID.

emails/welcome.ts

import { api } from "encore.dev/api";
import { secret } from "encore.dev/config";
import { ParcelWing, ParcelWingError } from "@parcelwing/node";
 
const parcelWingApiKey = secret("ParcelWingApiKey");
 
type SendWelcomeEmailParams = {
  email: string;
  firstName?: string;
};
 
type SendWelcomeEmailResponse = {
  id?: string;
  requestId?: string;
};
 
export const sendWelcomeEmail = api(
  { expose: true, method: "POST", path: "/emails/welcome" },
  async (params: SendWelcomeEmailParams): Promise<SendWelcomeEmailResponse> => {
    const parcelWing = new ParcelWing({
      apiKey: parcelWingApiKey(),
    });
 
    try {
      const [message] = await parcelWing.emails.send({
        from: "Acme <[email protected]>",
        to: params.email,
        template_alias: "welcome_email",
        template_params: {
          first_name: params.firstName ?? "friend",
        },
      });
 
      return { id: message?.id };
    } catch (error) {
      if (error instanceof ParcelWingError) {
        return { requestId: error.requestId };
      }
 
      throw error;
    }
  },
);

Production notes

Use Encore secrets for ParcelWingApiKey rather than environment literals.
Validate public API inputs before sending email.
Consider making internal email endpoints non-public unless the browser needs direct access.