@opencoredev/email-sdk3.1.031.7 kB
#!/usr/bin/env node
import { readFile } from "node:fs/promises";
import { basename } from "node:path";
import { brevo } from "./brevo.js";
import { cloudflare } from "./cloudflare.js";
import { createEmailClient } from "./core.js";
import { EmailSdkError } from "./errors.js";
import { isStringMember, jsonString, parseJsonStrict } from "./internal/decode.js";
import { runDoctor } from "./doctor.js";
import { graph } from "./graph.js";
import { iterable } from "./iterable.js";
import { jetemail } from "./jetemail.js";
import { lettermint } from "./lettermint.js";
import { lettr } from "./lettr.js";
import { loops } from "./loops.js";
import { mailchimp } from "./mailchimp.js";
import { mailersend } from "./mailersend.js";
import { mailgun } from "./mailgun.js";
import { mailpace } from "./mailpace.js";
import { mailtrap } from "./mailtrap.js";
import { plunk } from "./plunk.js";
import { postmark } from "./postmark.js";
import { primitive } from "./primitive.js";
import { resend } from "./resend.js";
import { scaleway } from "./scaleway.js";
import { sequenzy } from "./sequenzy.js";
import { ses } from "./ses.js";
import { sendgrid } from "./sendgrid.js";
import { sendheron } from "./sendheron.js";
import { helo } from "./helo.js";
import { smtp } from "./smtp.js";
import { sparkpost } from "./sparkpost.js";
import type {
EmailAttachment,
EmailHeader,
EmailMessage,
EmailAdapter,
EmailTag,
} from "./types.js";
import {
getTelemetry,
getTelemetryStatus,
normalizeAdapterName,
setTelemetryPreference,
setTelemetrySource,
} from "./telemetry.js";
import { SUPPORTED_MESSAGE_FIELDS } from "./utils.js";
import { unosend } from "./unosend.js";
import { zeptomail } from "./zeptomail.js";
type CliFlags = Record<string, string | string[] | true>;
type AdapterFactory = (flags: CliFlags) => EmailAdapter;
type SupportedAdapterName = keyof typeof SUPPORTED_MESSAGE_FIELDS;
type PackageInfo = {
name: string;
version: string;
};
const providerDocs = [
{ name: "resend", env: ["RESEND_API_KEY"], note: "Resend Email API" },
{ name: "postmark", env: ["POSTMARK_SERVER_TOKEN"], note: "Postmark Email API" },
{ name: "sendgrid", env: ["SENDGRID_API_KEY"], note: "Twilio SendGrid Mail Send API" },
{
name: "cloudflare",
env: ["CLOUDFLARE_API_TOKEN", "CLOUDFLARE_ACCOUNT_ID"],
note: "Cloudflare Email Sending REST API",
},
{
name: "graph",
env: ["MS_GRAPH_TENANT_ID", "MS_GRAPH_CLIENT_ID", "MS_GRAPH_CLIENT_SECRET", "MS_GRAPH_USER"],
note: "Microsoft Graph sendMail API",
},
{ name: "unosend", env: ["UNOSEND_API_KEY"], note: "Unosend REST API" },
{
name: "iterable",
env: ["ITERABLE_API_KEY", "ITERABLE_CAMPAIGN_ID"],
note: "Iterable target email API",
},
{
name: "ses",
env: ["AWS_ACCESS_KEY_ID", "AWS_SECRET_ACCESS_KEY", "AWS_REGION"],
note: "AWS SES v2 SendEmail API",
},
{ name: "mailgun", env: ["MAILGUN_API_KEY", "MAILGUN_DOMAIN"], note: "Mailgun Messages API" },
{ name: "mailersend", env: ["MAILERSEND_API_KEY"], note: "MailerSend Email API" },
{ name: "brevo", env: ["BREVO_API_KEY"], note: "Brevo transactional email API" },
{ name: "mailchimp", env: ["MAILCHIMP_API_KEY"], note: "Mailchimp Transactional" },
{ name: "sparkpost", env: ["SPARKPOST_API_KEY"], note: "SparkPost Transmissions API" },
{
name: "loops",
env: ["LOOPS_API_KEY", "LOOPS_TRANSACTIONAL_ID"],
note: "Loops transactional email",
},
{ name: "sequenzy", env: ["SEQUENZY_API_KEY"], note: "Sequenzy transactional email API" },
{ name: "jetemail", env: ["JETEMAIL_API_KEY"], note: "JetEmail transactional email API" },
{ name: "lettermint", env: ["LETTERMINT_API_TOKEN"], note: "Lettermint sending API" },
{ name: "lettr", env: ["LETTR_API_KEY"], note: "Lettr transactional email API" },
{ name: "primitive", env: ["PRIMITIVE_API_KEY"], note: "Primitive email API for AI agents" },
{ name: "plunk", env: ["PLUNK_API_KEY"], note: "Plunk public send API" },
{ name: "mailtrap", env: ["MAILTRAP_API_KEY"], note: "Mailtrap Email Sending API" },
{
name: "scaleway",
env: ["SCALEWAY_SECRET_KEY", "SCALEWAY_PROJECT_ID"],
note: "Scaleway Transactional Email",
},
{ name: "zeptomail", env: ["ZEPTOMAIL_TOKEN"], note: "Zoho ZeptoMail API" },
{ name: "mailpace", env: ["MAILPACE_API_KEY"], note: "MailPace send API" },
{ name: "sendheron", env: ["SENDHERON_API_KEY"], note: "SendHeron transactional email API" },
{ name: "helo", env: ["HELO_API_KEY"], note: "Helo transactional send API" },
{ name: "smtp", env: ["SMTP_HOST"], note: "Built-in SMTP transport" },
] as const satisfies ReadonlyArray<{
name: SupportedAdapterName;
env: readonly string[];
note: string;
}>;
type ProviderName = (typeof providerDocs)[number]["name"];
const factories = {
resend: (flags) => resend({ apiKey: flagOrEnv(flags, "api-key", "RESEND_API_KEY") }),
postmark: (flags) =>
postmark({
serverToken: flagOrEnv(flags, "server-token", "POSTMARK_SERVER_TOKEN"),
messageStream: stringFlag(flags, "message-stream") ?? process.env.POSTMARK_MESSAGE_STREAM,
}),
sendgrid: (flags) => sendgrid({ apiKey: flagOrEnv(flags, "api-key", "SENDGRID_API_KEY") }),
cloudflare: (flags) =>
cloudflare({
apiToken: flagOrEnv(flags, "api-token", "CLOUDFLARE_API_TOKEN"),
accountId: flagOrEnv(flags, "account-id", "CLOUDFLARE_ACCOUNT_ID"),
baseUrl: stringFlag(flags, "base-url") ?? process.env.CLOUDFLARE_BASE_URL,
}),
graph: (flags) =>
graph({
tenantId: flagOrEnv(flags, "tenant-id", "MS_GRAPH_TENANT_ID"),
clientId: flagOrEnv(flags, "client-id", "MS_GRAPH_CLIENT_ID"),
clientSecret: flagOrEnv(flags, "client-secret", "MS_GRAPH_CLIENT_SECRET"),
user: flagOrEnv(flags, "user", "MS_GRAPH_USER"),
baseUrl: stringFlag(flags, "base-url") ?? process.env.MS_GRAPH_BASE_URL,
tokenUrl: stringFlag(flags, "token-url") ?? process.env.MS_GRAPH_TOKEN_URL,
scope: stringFlag(flags, "scope") ?? process.env.MS_GRAPH_SCOPE,
saveToSentItems: booleanFlag(flags, "save-to-sent-items") ?? booleanEnv("MS_GRAPH_SAVE_TO_SENT_ITEMS"),
}),
unosend: (flags) =>
unosend({
apiKey: flagOrEnv(flags, "api-key", "UNOSEND_API_KEY"),
baseUrl: stringFlag(flags, "base-url") ?? process.env.UNOSEND_BASE_URL,
}),
iterable: (flags) =>
iterable({
apiKey: flagOrEnv(flags, "api-key", "ITERABLE_API_KEY"),
campaignId: numberFlagOrEnv(flags, "campaign-id", "ITERABLE_CAMPAIGN_ID"),
baseUrl: stringFlag(flags, "base-url") ?? process.env.ITERABLE_BASE_URL,
sendAt: stringFlag(flags, "iterable-send-at") ?? process.env.ITERABLE_SEND_AT,
allowRepeatMarketingSends:
booleanFlag(flags, "allow-repeat-marketing-sends") ??
booleanEnv("ITERABLE_ALLOW_REPEAT_MARKETING_SENDS"),
}),
ses: (flags) =>
ses({
accessKeyId: flagOrEnv(flags, "access-key-id", "AWS_ACCESS_KEY_ID"),
secretAccessKey: flagOrEnv(flags, "secret-access-key", "AWS_SECRET_ACCESS_KEY"),
sessionToken: stringFlag(flags, "session-token") ?? process.env.AWS_SESSION_TOKEN,
region: flagOrEnv(flags, "region", "AWS_REGION"),
baseUrl: stringFlag(flags, "base-url") ?? process.env.AWS_SES_BASE_URL,
configurationSetName:
stringFlag(flags, "configuration-set") ?? process.env.AWS_SES_CONFIGURATION_SET,
}),
mailgun: (flags) =>
mailgun({
apiKey: flagOrEnv(flags, "api-key", "MAILGUN_API_KEY"),
domain: flagOrEnv(flags, "domain", "MAILGUN_DOMAIN"),
baseUrl: stringFlag(flags, "base-url") ?? process.env.MAILGUN_BASE_URL,
}),
mailersend: (flags) => mailersend({ apiKey: flagOrEnv(flags, "api-key", "MAILERSEND_API_KEY") }),
brevo: (flags) => brevo({ apiKey: flagOrEnv(flags, "api-key", "BREVO_API_KEY") }),
mailchimp: (flags) => mailchimp({ apiKey: flagOrEnv(flags, "api-key", "MAILCHIMP_API_KEY") }),
sparkpost: (flags) => sparkpost({ apiKey: flagOrEnv(flags, "api-key", "SPARKPOST_API_KEY") }),
loops: (flags) =>
loops({
apiKey: flagOrEnv(flags, "api-key", "LOOPS_API_KEY"),
transactionalId: flagOrEnv(flags, "transactional-id", "LOOPS_TRANSACTIONAL_ID"),
}),
sequenzy: (flags) =>
sequenzy({
apiKey: flagOrEnv(flags, "api-key", "SEQUENZY_API_KEY"),
baseUrl: stringFlag(flags, "base-url") ?? process.env.SEQUENZY_BASE_URL,
}),
jetemail: (flags) =>
jetemail({
apiKey: flagOrEnv(flags, "api-key", "JETEMAIL_API_KEY"),
baseUrl: stringFlag(flags, "base-url") ?? process.env.JETEMAIL_BASE_URL,
}),
lettermint: (flags) =>
lettermint({
apiToken: flagOrEnv(flags, "api-token", "LETTERMINT_API_TOKEN"),
baseUrl: stringFlag(flags, "base-url") ?? process.env.LETTERMINT_BASE_URL,
route: stringFlag(flags, "route") ?? process.env.LETTERMINT_ROUTE,
}),
lettr: (flags) =>
lettr({
apiKey: flagOrEnv(flags, "api-key", "LETTR_API_KEY"),
baseUrl: stringFlag(flags, "base-url") ?? process.env.LETTR_BASE_URL,
}),
primitive: (flags) =>
primitive({
apiKey: flagOrEnv(flags, "api-key", "PRIMITIVE_API_KEY"),
baseUrl: stringFlag(flags, "base-url") ?? process.env.PRIMITIVE_BASE_URL,
}),
plunk: (flags) => plunk({ apiKey: flagOrEnv(flags, "api-key", "PLUNK_API_KEY") }),
mailtrap: (flags) => mailtrap({ apiKey: flagOrEnv(flags, "api-key", "MAILTRAP_API_KEY") }),
scaleway: (flags) =>
scaleway({
secretKey: flagOrEnv(flags, "secret-key", "SCALEWAY_SECRET_KEY"),
projectId: flagOrEnv(flags, "project-id", "SCALEWAY_PROJECT_ID"),
region: stringFlag(flags, "region") ?? process.env.SCALEWAY_REGION,
}),
zeptomail: (flags) => zeptomail({ token: flagOrEnv(flags, "token", "ZEPTOMAIL_TOKEN") }),
mailpace: (flags) => mailpace({ apiKey: flagOrEnv(flags, "api-key", "MAILPACE_API_KEY") }),
sendheron: (flags) =>
sendheron({
apiKey: flagOrEnv(flags, "api-key", "SENDHERON_API_KEY"),
baseUrl: stringFlag(flags, "base-url") ?? process.env.SENDHERON_BASE_URL,
}),
helo: (flags) =>
helo({
apiKey: flagOrEnv(flags, "api-key", "HELO_API_KEY"),
channelId: stringFlag(flags, "channel-id") ?? process.env.HELO_CHANNEL_ID,
baseUrl: stringFlag(flags, "base-url") ?? process.env.HELO_BASE_URL,
}),
smtp: (flags) =>
smtp({
host: flagOrEnv(flags, "host", "SMTP_HOST"),
port: Number(stringFlag(flags, "port") ?? process.env.SMTP_PORT ?? 587),
secure: truthyFlag(flags, "secure") || process.env.SMTP_SECURE === "true",
requireTLS: truthyFlag(flags, "require-tls") || process.env.SMTP_REQUIRE_TLS === "true",
allowInsecureAuth:
truthyFlag(flags, "allow-insecure-auth") || process.env.SMTP_ALLOW_INSECURE_AUTH === "true",
auth:
stringFlag(flags, "user") || process.env.SMTP_USER
? {
user: flagOrEnv(flags, "user", "SMTP_USER"),
pass: flagOrEnv(flags, "pass", "SMTP_PASS"),
}
: undefined,
}),
} satisfies Record<ProviderName, AdapterFactory>;
const envFlagNames = new Map<string, string>([
["RESEND_API_KEY", "api-key"],
["POSTMARK_SERVER_TOKEN", "server-token"],
["SENDGRID_API_KEY", "api-key"],
["CLOUDFLARE_API_TOKEN", "api-token"],
["CLOUDFLARE_ACCOUNT_ID", "account-id"],
["MS_GRAPH_TENANT_ID", "tenant-id"],
["MS_GRAPH_CLIENT_ID", "client-id"],
["MS_GRAPH_CLIENT_SECRET", "client-secret"],
["MS_GRAPH_USER", "user"],
["MS_GRAPH_TOKEN_URL", "token-url"],
["MS_GRAPH_SCOPE", "scope"],
["UNOSEND_API_KEY", "api-key"],
["ITERABLE_API_KEY", "api-key"],
["ITERABLE_CAMPAIGN_ID", "campaign-id"],
["AWS_ACCESS_KEY_ID", "access-key-id"],
["AWS_SECRET_ACCESS_KEY", "secret-access-key"],
["AWS_REGION", "region"],
["MAILGUN_API_KEY", "api-key"],
["MAILGUN_DOMAIN", "domain"],
["MAILERSEND_API_KEY", "api-key"],
["BREVO_API_KEY", "api-key"],
["MAILCHIMP_API_KEY", "api-key"],
["SPARKPOST_API_KEY", "api-key"],
["LOOPS_API_KEY", "api-key"],
["LOOPS_TRANSACTIONAL_ID", "transactional-id"],
["SEQUENZY_API_KEY", "api-key"],
["JETEMAIL_API_KEY", "api-key"],
["LETTERMINT_API_TOKEN", "api-token"],
["LETTR_API_KEY", "api-key"],
["PRIMITIVE_API_KEY", "api-key"],
["PLUNK_API_KEY", "api-key"],
["MAILTRAP_API_KEY", "api-key"],
["SCALEWAY_SECRET_KEY", "secret-key"],
["SCALEWAY_PROJECT_ID", "project-id"],
["ZEPTOMAIL_TOKEN", "token"],
["MAILPACE_API_KEY", "api-key"],
["SENDHERON_API_KEY", "api-key"],
["HELO_API_KEY", "api-key"],
["SMTP_HOST", "host"],
]);
async function main(command: string | undefined, flags: CliFlags, args: string[]) {
if (!command || command === "help" || command === "--help" || command === "-h") {
printHelp();
return;
}
if (command === "version" || command === "--version" || command === "-v") {
await printVersion(flags);
return;
}
if (command === "adapters" || command === "providers") {
printAdapters(flags);
return;
}
if (command === "doctor") {
await doctor(flags);
return;
}
if (command === "telemetry") {
telemetryCommand(args[0]);
return;
}
if (command !== "send") {
fail(`Unknown command "${command}".`);
}
const providerName = selectedAdapter(flags) ?? detectProvider();
const message = await buildMessage(flags);
if (truthyFlag(flags, "dry-run")) {
const adapter = createProvider(providerName, dryRunFlags(providerName, flags));
const client = createEmailClient({ adapters: [adapter] });
await client.validate(message);
console.log(
JSON.stringify(
{
ok: true,
adapter: providerName,
message: redactMessageForDryRun(message),
},
null,
2,
),
);
return;
}
const provider = createProvider(providerName, flags);
const client = createEmailClient({ adapters: [provider] });
// setTelemetrySource("cli") at process start already tags this client's events.
const response = await client.send(message);
console.log(JSON.stringify(response, null, 2));
}
function createProvider(name: string, flags: CliFlags): EmailAdapter {
if (!isProviderName(name)) {
fail(`Unsupported adapter "${name}". Run \`email-sdk adapters\` to see supported adapters.`);
}
return factories[name](flags);
}
function dryRunFlags(name: string, flags: CliFlags) {
if (!isProviderName(name)) {
fail(`Unsupported adapter "${name}". Run \`email-sdk adapters\` to see supported adapters.`);
}
const defaults = Object.fromEntries(
providerDocs
.find((adapter) => adapter.name === name)!
.env.map((environmentName) => [
envFlagNames.get(environmentName),
environmentName.endsWith("CAMPAIGN_ID") ? "1" : "dry-run",
]),
);
return { ...defaults, ...flags };
}
function isProviderName(name: string): name is ProviderName {
return Object.prototype.hasOwnProperty.call(factories, name);
}
function detectProvider() {
for (const provider of providerDocs) {
if (provider.env.every((name) => process.env[name])) {
return provider.name;
}
}
fail("Pass --adapter or set the required environment for one adapter.");
}
function printAdapters(flags: CliFlags) {
const json = truthyFlag(flags, "json");
if (json) {
console.log(JSON.stringify(providerDocs, null, 2));
return;
}
console.log("Email SDK adapters\n");
for (const provider of providerDocs) {
console.log(
`${provider.name.padEnd(12)} ${provider.env.join(", ").padEnd(42)} ${provider.note}`,
);
}
}
async function doctor(flags: CliFlags) {
const providerName =
selectedAdapter(flags) ??
providerDocs.find((item) => item.env.every((name) => process.env[name]?.trim()))?.name;
const provider = providerDocs.find((item) => item.name === providerName);
const missing = provider?.env.filter((name) => !hasEnvOrFlag(flags, name)) ?? [];
const live = truthyFlag(flags, "live");
const from = flags.from === undefined ? undefined : (stringFlag(flags, "from") ?? "");
const credentialEnv = provider?.name === "graph" ? "MS_GRAPH_CLIENT_SECRET" : provider?.env[0];
const credentialFlag = credentialEnv ? envFlagNames.get(credentialEnv) : undefined;
const result = await runDoctor({
adapter: provider?.name ?? "unknown",
configured: Boolean(provider) && missing.length === 0,
credential:
credentialFlag && flags[credentialFlag] !== undefined
? (stringFlag(flags, credentialFlag) ?? "")
: credentialEnv
? process.env[credentialEnv]
: undefined,
live,
from,
baseUrl:
flags["base-url"] !== undefined
? (stringFlag(flags, "base-url") ?? "")
: provider
? process.env[`${provider.name.toUpperCase()}_BASE_URL`]
: undefined,
tenantId: provider?.name === "graph" ? stringFlag(flags, "tenant-id") ?? process.env.MS_GRAPH_TENANT_ID : undefined,
clientId: provider?.name === "graph" ? stringFlag(flags, "client-id") ?? process.env.MS_GRAPH_CLIENT_ID : undefined,
tokenUrl: provider?.name === "graph" ? stringFlag(flags, "token-url") ?? process.env.MS_GRAPH_TOKEN_URL : undefined,
scope: provider?.name === "graph" ? stringFlag(flags, "scope") ?? process.env.MS_GRAPH_SCOPE : undefined,
});
if (!provider)
result.checks.configuration.message =
"Select a supported adapter with --adapter or set its required environment variables. Run `email-sdk adapters` for options.";
if (truthyFlag(flags, "json")) {
console.log(JSON.stringify(result, null, 2));
} else if (result.ok && !live) {
console.log(`${result.adapter} looks configured.`);
} else {
if (missing.length > 0)
console.error(`Missing environment for ${result.adapter}: ${missing.join(", ")}`);
for (const [name, item] of Object.entries(result.checks)) {
console.log(`${name}: ${item.status} — ${item.message}`);
}
}
if (!result.ok) process.exitCode = 1;
}
function hasEnvOrFlag(flags: CliFlags, env: string) {
const flag = envFlagNames.get(env);
const value = flag && flags[flag] !== undefined ? stringFlag(flags, flag) : process.env[env];
return Boolean(value?.trim());
}
async function printVersion(flags: CliFlags) {
const packageInfo = await readPackageInfo();
if (truthyFlag(flags, "json")) {
console.log(JSON.stringify(packageInfo, null, 2));
return;
}
console.log(`${packageInfo.name} ${packageInfo.version}`);
}
async function readPackageInfo(): Promise<PackageInfo> {
try {
const packageJson = parseJsonStrict(
await readFile(new URL("../package.json", import.meta.url), "utf8"),
);
return {
name: jsonString(packageJson, "name") ?? "@opencoredev/email-sdk",
version: jsonString(packageJson, "version") ?? "0.0.0",
};
} catch {
return {
name: "@opencoredev/email-sdk",
version: "0.0.0",
};
}
}
function parseFlags(args: string[]) {
const flags: CliFlags = {};
for (let index = 0; index < args.length; index += 1) {
const current = args[index];
if (!current?.startsWith("--")) {
continue;
}
const [key, inlineValue] = current.slice(2).split(/=(.*)/s);
if (!key) {
continue;
}
if (inlineValue !== undefined) {
setFlag(flags, key, inlineValue);
continue;
}
const next = args[index + 1];
if (!next || next.startsWith("--")) {
setFlag(flags, key, true);
continue;
}
setFlag(flags, key, next);
index += 1;
}
return flags;
}
function setFlag(flags: CliFlags, key: string, value: string | true) {
const current = flags[key];
if (current === undefined) {
flags[key] = value;
return;
}
if (Array.isArray(current)) {
current.push(String(value));
return;
}
flags[key] = [String(current), String(value)];
}
function requiredFlag(flags: CliFlags, name: string) {
const value = stringFlag(flags, name);
if (!value) {
fail(`Missing --${name}.`);
}
return value;
}
function flagOrEnv(flags: CliFlags, flag: string, env: string) {
const value = stringFlag(flags, flag) ?? process.env[env];
if (!value) {
fail(`Missing --${flag} or ${env}.`);
}
return value;
}
function numberFlagOrEnv(flags: CliFlags, flag: string, env: string) {
const raw = flagOrEnv(flags, flag, env);
const value = Number(raw);
if (!Number.isFinite(value)) {
fail(`Invalid --${flag} or ${env}. Expected a number.`);
}
return value;
}
function stringFlag(flags: CliFlags, name: string) {
const value = flags[name];
if (Array.isArray(value)) {
return value.at(-1);
}
return isStringMember(value) ? value : undefined;
}
function stringFlags(flags: CliFlags, name: string) {
const value = flags[name];
if (Array.isArray(value)) {
return value;
}
return isStringMember(value) ? [value] : [];
}
function selectedAdapter(flags: CliFlags) {
return stringFlag(flags, "adapter") ?? stringFlag(flags, "provider");
}
function truthyFlag(flags: CliFlags, name: string) {
const value = flags[name];
return value === true || value === "true" || value === "1";
}
function booleanFlag(flags: CliFlags, name: string) {
const value = flags[name];
if (value === undefined) {
return undefined;
}
return value === true || value === "true" || value === "1";
}
function booleanEnv(name: string) {
const value = process.env[name];
if (value === undefined) {
return undefined;
}
return value === "true" || value === "1";
}
async function buildMessage(flags: CliFlags): Promise<EmailMessage> {
const messagePath = stringFlag(flags, "message");
// SAFETY: The message file is caller-authored input that is only shaped here. The client
// validates the assembled message (sender, recipients, subject, content, and adapter fields)
// before any adapter sends it.
const fromFile = messagePath
? (JSON.parse(await readFile(messagePath, "utf8")) as Partial<EmailMessage>)
: {};
const message: Partial<EmailMessage> = { ...fromFile };
if (stringFlag(flags, "from")) message.from = stringFlag(flags, "from")!;
if (stringFlag(flags, "to")) message.to = splitAddresses(requiredFlag(flags, "to"));
if (stringFlag(flags, "subject")) message.subject = stringFlag(flags, "subject")!;
if (stringFlag(flags, "text")) message.text = stringFlag(flags, "text");
if (stringFlag(flags, "html")) message.html = stringFlag(flags, "html");
if (stringFlag(flags, "cc")) message.cc = splitAddresses(requiredFlag(flags, "cc"));
if (stringFlag(flags, "bcc")) message.bcc = splitAddresses(requiredFlag(flags, "bcc"));
if (stringFlag(flags, "reply-to"))
message.replyTo = splitAddresses(requiredFlag(flags, "reply-to"));
if (stringFlag(flags, "send-at"))
// SAFETY: sendAt is checked as an RFC 3339 timestamp when the client validates the message.
message.sendAt = stringFlag(flags, "send-at") as EmailMessage["sendAt"];
const headers = parseHeaders(stringFlags(flags, "header"));
if (headers.length > 0) message.headers = headers;
const tags = parseTags(stringFlags(flags, "tag"));
if (tags.length > 0) message.tags = tags;
const metadata = parseMetadata(stringFlags(flags, "metadata"));
if (Object.keys(metadata).length > 0) message.metadata = metadata;
const attachments = parseAttachments([
...stringFlags(flags, "attachment"),
...stringFlags(flags, "attach"),
]);
if (attachments.length > 0) message.attachments = attachments;
// SAFETY: Required fields may still be missing here; the client's message validation
// rejects an incomplete message with an EmailValidationError before sending.
return message as EmailMessage;
}
function splitAddresses(value: string) {
return value
.split(",")
.map((item) => item.trim())
.filter(Boolean);
}
function parseHeaders(values: string[]): EmailHeader[] {
return values.map((value) => {
const index = value.indexOf(":");
if (index <= 0) {
fail(`Invalid --header "${value}". Use "Name: value".`);
}
return {
name: value.slice(0, index).trim(),
value: value.slice(index + 1).trim(),
};
});
}
function parseTags(values: string[]): EmailTag[] {
return values.map((value) => {
const [name, tagValue] = splitPair(value, "tag");
return { name, value: tagValue };
});
}
function parseMetadata(values: string[]) {
return Object.fromEntries(values.map((value) => splitPair(value, "metadata")));
}
function splitPair(value: string, flag: string): [string, string] {
const index = value.indexOf("=");
if (index <= 0) {
fail(`Invalid --${flag} "${value}". Use "name=value".`);
}
return [value.slice(0, index).trim(), value.slice(index + 1).trim()];
}
function parseAttachments(values: string[]): EmailAttachment[] {
return values.map((value) => {
const [path, contentType] = value.split(/:(.*)/s);
if (!path) {
fail("Invalid --attachment. Pass a file path.");
}
return {
filename: basename(path),
path,
contentType: contentType || undefined,
};
});
}
function redactMessageForDryRun(message: EmailMessage) {
return {
...message,
attachments: message.attachments?.map((attachment) => ({
filename: attachment.filename,
path: attachment.path,
contentType: attachment.contentType,
contentId: attachment.contentId,
disposition: attachment.disposition,
})),
};
}
function printHelp() {
console.log(`Email SDK
Usage:
email-sdk version
email-sdk adapters
RESEND_API_KEY="re_..." email-sdk doctor --adapter resend
email-sdk send --adapter resend --from you@example.com --to them@example.com --subject "Hello" --text "It works"
email-sdk telemetry [status|disable|enable]
Doctor options:
--live Explicitly check authentication without sending email.
--from <address> Check sender readiness (requires --live; Resend only).
--json Print configuration, authentication, and sender statuses.
--api-key <key> Overrides the selected adapter's API key environment.
--api-token <token> Overrides token environment (including Lettermint).
--base-url <url> Test-only: fixed provider base or 127.0.0.1/[::1] fixture URL.
--token-url <url> Graph OAuth token endpoint (or MS_GRAPH_TOKEN_URL).
--scope <scope> Graph OAuth scope (or MS_GRAPH_SCOPE).
Default checks configuration only and makes no provider request.
Authentication is not delivery proof. The CLI does not load .env files.
Exit status: 0 when every requested check passes, 1 otherwise.
Send options:
--adapter <name> Adapter routing name. Run "email-sdk adapters".
--provider <name> Alias for --adapter.
--from <address> Sender address.
--to <addresses> Comma-separated recipient addresses.
--subject <subject> Message subject.
--text <body> Plain text body.
--html <body> HTML body.
--cc <addresses> Comma-separated CC addresses.
--bcc <addresses> Comma-separated BCC addresses.
--reply-to <addresses> Comma-separated reply-to addresses.
--header <name:value> Add a custom header. Repeatable.
--tag <name=value> Add a provider tag. Repeatable.
--metadata <key=value> Add provider metadata. Repeatable.
--attachment <path[:type]> Attach a local file. Repeatable.
--message <path> Read the EmailMessage JSON payload from a file.
--send-at <rfc3339> Schedule the message on capable adapters.
--dry-run Validate input and print the send plan without sending.
--base-url <url> Overrides supported adapter base URL variables.
Cloudflare options:
--api-token <token> Overrides CLOUDFLARE_API_TOKEN.
--account-id <account> Overrides CLOUDFLARE_ACCOUNT_ID.
Iterable options:
--campaign-id <id> Overrides ITERABLE_CAMPAIGN_ID.
--iterable-send-at <utc> Overrides ITERABLE_SEND_AT for Iterable's campaign API.
--allow-repeat-marketing-sends
Allows repeat marketing sends.
SMTP options:
--host <host> Overrides SMTP_HOST.
--port <port> Overrides SMTP_PORT.
--secure Use TLS from the start.
--require-tls Require STARTTLS.
--allow-insecure-auth Allow SMTP AUTH without TLS.
--user <user> Overrides SMTP_USER.
--pass <pass> Overrides SMTP_PASS.
`);
}
function telemetryCommand(action = "status") {
if (action === "disable" || action === "enable") {
const path = setTelemetryPreference(action === "enable");
console.log(`Telemetry ${action}d for this machine (${path}).`);
const status = getTelemetryStatus();
if (action === "enable" && !status.enabled) {
console.log(`Telemetry is still disabled by ${status.reason}.`);
}
return;
}
if (action !== "status") {
fail(`Unknown telemetry action "${action}". Use status, disable, or enable.`);
}
const status = getTelemetryStatus();
if (status.enabled) {
console.log("Telemetry is enabled (default). Run `email-sdk telemetry disable` to opt out.");
return;
}
if (status.reason === "config-unreadable") {
console.log(
`Telemetry is disabled because ${status.configPath} is unreadable. Run \`email-sdk telemetry disable\` or \`enable\` to rewrite it.`,
);
return;
}
const reason = status.reason === "config" ? status.configPath : status.reason;
console.log(`Telemetry is disabled (${reason}).`);
}
class CliFailure extends Error {}
function fail(message: string): never {
throw new CliFailure(message);
}
function normalizeCliCommand(command: string | undefined) {
if (!command || command === "help" || command === "--help" || command === "-h") {
return "help";
}
if (command === "version" || command === "--version" || command === "-v") {
return "version";
}
if (command === "adapters" || command === "providers") {
return "adapters";
}
if (command === "doctor" || command === "send") {
return command;
}
return "unknown";
}
async function captureCliRun(input: {
command: string | undefined;
flags: CliFlags;
success: boolean;
startedAt: number;
error?: unknown;
}) {
const adapter = selectedAdapter(input.flags);
const telemetry = getTelemetry();
await telemetry.capture("cli command run", {
command: normalizeCliCommand(input.command),
adapter: adapter ? normalizeAdapterName(adapter) : undefined,
dry_run: truthyFlag(input.flags, "dry-run"),
source: "cli",
success: input.success,
duration_ms: Date.now() - input.startedAt,
error_code:
input.error instanceof EmailSdkError
? input.error.code
: input.success
? undefined
: "cli_error",
});
// Settle the fire-and-forget captures from core.ts before process.exit(1)
// can tear down the event loop and silently drop them.
await telemetry.flush();
}
const startedAt = Date.now();
const [cliCommand, ...cliArgs] = process.argv.slice(2);
const cliFlags = parseFlags(cliArgs);
// Managing the opt-out never reports anything, even when the command fails.
const reportsTelemetry = cliCommand !== "telemetry";
// Tag every telemetry event from this process (client created, email sent,
// exceptions) as CLI traffic before any client is constructed.
setTelemetrySource("cli");
try {
await main(cliCommand, cliFlags, cliArgs);
if (reportsTelemetry) {
await captureCliRun({ command: cliCommand, flags: cliFlags, success: true, startedAt });
}
} catch (error) {
if (reportsTelemetry && !(error instanceof CliFailure) && !(error instanceof EmailSdkError)) {
// Unexpected crash, not a usage or provider failure. Reported before the run
// summary so captureCliRun's flush() settles it too. Errors rethrown out of
// client.send were already reported there; the per-object dedupe drops this one.
void getTelemetry().captureException(error, {
source: "cli",
handled: false,
command: normalizeCliCommand(cliCommand),
});
}
if (reportsTelemetry) {
await captureCliRun({ command: cliCommand, flags: cliFlags, success: false, startedAt, error });
}
if (error instanceof CliFailure || error instanceof EmailSdkError) {
console.error(error.message);
process.exit(1);
}
throw error;
}
Shown as plain text from the published tarball, after apm checked it against the version's checksum. Nothing in it runs on this page.