Introduction

Choose your sending path

Before sending: configure an implementation with credentials and an authorized sender. Installing this contract alone does not connect an email service. Examples use placeholder recipients and do not send mail from this documentation.

Core Concepts

The interface separates email operations into four functions:

The sending functions return typed delivery responses. GetCapabilities returns feature flags and limits instead. A successful send means the provider accepted the request; inspect status rather than treating acceptance as confirmed delivery.

Installation

npm install @antelopejs/interface-email

Email Address Types

Recipients, senders, and reply-to addresses all accept the EmailAddress type. This type supports two formats: a plain string or an object with an optional display name.

String format

Pass an email address directly as a string:

import type { EmailAddress } from "@antelopejs/interface-email";

const to: EmailAddress = "[email protected]";

Object format with EmailAddressObject

Use the object format to include a display name alongside the address:

import { EmailAddressObject } from "@antelopejs/interface-email";

const sender: EmailAddressObject = {
  email: "[email protected]",
  name: "MyApp Support",
};

The EmailAddress union type

The EmailAddress type is a union of both formats. All address fields in the interface accept either form:

import { EmailAddress } from "@antelopejs/interface-email";

// Both are valid EmailAddress values
const simple: EmailAddress = "[email protected]";
const detailed: EmailAddress = { email: "[email protected]", name: "Hello" };

Fields like to, cc, and bcc also accept arrays of EmailAddress, so you can mix formats freely:

import { Send } from "@antelopejs/interface-email";

await Send({
  to: ["[email protected]", { email: "[email protected]", name: "Bob" }],
  subject: "Team Update",
  text: "Here is the latest update.",
});

Provider Capabilities

Not all email providers support every feature. The GetCapabilities function returns a ProviderCapabilities object describing the provider's name, limits, and supported features.

import { GetCapabilities } from "@antelopejs/interface-email";

const capabilities = await GetCapabilities();

console.log(capabilities.name); // e.g., "sendgrid"
console.log(capabilities.features.batch); // true or false
console.log(capabilities.features.scheduling); // true or false
console.log(capabilities.maxRecipients); // e.g., 1000

The ProviderFeatures object includes the following flags:

Check capabilities before using optional features to ensure your code works across providers:

import {
  GetCapabilities,
  Send,
  type EmailParams,
} from "@antelopejs/interface-email";

const caps = await GetCapabilities();

const params: EmailParams = {
  to: "[email protected]",
  subject: "Hello",
  html: "<p>Welcome!</p>",
};

if (caps.features.scheduling) {
  params.schedule = { sendAt: new Date(Date.now() + 60 * 60 * 1000) };
}

await Send(params);

Capability limits are optional: maxRecipients, maxBatchSize, maxAttachmentSize, and maxEmailSize may be absent. Size limits are in bytes. An absent limit is not a promise of unlimited capacity; check your provider configuration. version is optional provider metadata.

Next Steps

• Sending Emails -- Learn about all email parameters, templates, batch sending, and delivery responses.
• Attachments -- Attach files using buffers, base64, file paths, or URLs.