SendEmailOptions

Reference for the SendEmailOptions type used with the sendEmail method.

This is a detailed reference for email-related types in Stack Auth. If you’re looking for a more high-level overview, please refer to our guide on the email system.

SendEmailOptions

Options for sending emails via the sendEmail method on StackServerApp.

Table of Contents

Recipients

You must provide exactly one of userIds or allUsers.

Content

You must provide exactly one of html, templateId, or draftId.

Options

Usage

Choose a content method (html, templateId, or draftId) and a recipient method (userIds or allUsers):

Custom HTML

Provide custom HTML directly:

await stackServerApp.sendEmail({
  userIds: ["user-id-1"],
  subject: "Hello!",
  html: "<h1>Welcome</h1><p>Thanks for signing up!</p>",
});

Template

Use a template with variable substitution:

await stackServerApp.sendEmail({
  userIds: ["user-id-1"],
  templateId: "welcome-template",
  variables: {
    userName: "John Doe",
    activationUrl: "https://app.com/activate/token123",
  },
});

Draft

Send from a saved email draft:

await stackServerApp.sendEmail({
  allUsers: true,
  draftId: "my-draft-id",
});

Scheduled

Schedule an email for later delivery:

await stackServerApp.sendEmail({
  userIds: ["user-id-1"],
  templateId: "weekly-digest",
  scheduledAt: new Date("2025-01-15T09:00:00Z"),
});

The notificationCategoryName, themeId, scheduledAt, and variables properties work independently with any content method.