⭐️⭐️⭐️ Open-source, self-hosted alternative to Linear and Plane. Project management and issue tracking where teams and AI agents work side by side to plan and ship products.
TypeScript agenticagileai-agentsbug-reportingbug-trackerganttissue-trackerjirajira-alternativekanbanlinearlinear-alternativeopen-sourceproduct-managementproject-managementroadmapself-hostedsprint-planningteam-collaborationtrello-alternative
import nodemailer from 'nodemailer';
import { escapeHtml } from './templates/render';
export * from './locale';
export * from './templates/catalog';
export * from './templates/layout';
export * from './templates/render';
export type { CoreEmailKey, EmailText, EmailWords } from './templates/types';
// Outbound email transport, shared by the two senders in the app: project
// notifications (credentials per project) and authentication mail (credentials per
// instance). Where the credentials come from and how they are stored belong to the
// caller. ./templates holds what the emails say and how they look.
const HTTP_TIMEOUT_MS = 15_000;
// Microsoft 365 refuses a password once the mailbox has MFA, and is retiring password
// SMTP altogether. 'microsoft365' signs in as an app registration (client credentials,
// permission SMTP.SendAsApp) and presents the token over XOAUTH2 as `username`.
export type SmtpAuth = 'password' | 'microsoft365';
export interface MicrosoftOAuthConfig {
tenantId: string;
clientId: string;
clientSecret: string;
}
export interface SmtpConfig {
enabled: boolean;
host: string;
port: number | null;
encryption: 'none' | 'ssl' | 'tls';
username: string;
password: string;
timeout: number | null;
// Absent on configs stored before it existed: those are password ones.
auth?: SmtpAuth;
oauth?: MicrosoftOAuthConfig;
}
export interface ResendConfig {
enabled: boolean;
apiKey: string;
}
export interface EmailConfig {
smtp: SmtpConfig;
resend: ResendConfig;
// The From address. Falls back to EMAIL_FROM, then to the SMTP username.
from?: string | null;
}
export interface EmailMessage {
to: string;
subject: string;
text: string;
html: string;
idempotencyKey?: string;
}
export interface SendResult {
ok: boolean;
// Only meaningful when ok is false: true for a transient failure worth retrying
// (network error, timeout, rate limit, server error), false for a permanent one
// (bad credentials, rejected recipient, misconfiguration).
retryable?: boolean;
error?: string;
}
// The From address for outbound email. An explicit config value wins, then the
// EMAIL_FROM env var; for SMTP the username (usually the account's own address) is
// the last fallback. Resend has no natural fallback: it needs a verified sender.
function fromAddress(config: EmailConfig, provider: 'smtp' | 'resend'): string | null {
if (config.from && config.from.length > 0) return config.from;
const env = process.env.EMAIL_FROM ?? process.env.NOTIFICATIONS_EMAIL_FROM;
if (env && env.length > 0) return env;
if (provider === 'smtp' && config.smtp.username.length > 0) return config.smtp.username;
return null;
}
function smtpReady(smtp: SmtpConfig): boolean {
return smtp.enabled && smtp.host.length > 0;
}
// The address an email goes out from, with the provider sendEmail would pick.
export function senderAddress(config: EmailConfig): string | null {
return fromAddress(config, smtpReady(config.smtp) ? 'smtp' : 'resend');
}
class TokenError extends Error {
constructor(
message: string,
readonly retryable: boolean,
) {
super(message);
}
}
// A token lasts about an hour; reusing it spares Microsoft a sign-in per message.
const tokenCache = new Map<string, { token: string; expiresAt: number }>();
const TOKEN_MARGIN_MS = 60_000;
async function microsoftAccessToken(oauth: MicrosoftOAuthConfig): Promise<string> {
const key = `${oauth.tenantId}|${oauth.clientId}|${oauth.clientSecret}`;
const cached = tokenCache.get(key);
if (cached && cached.expiresAt - TOKEN_MARGIN_MS > Date.now()) return cached.token;
let res: Response;
try {
res = await fetch(
`https://login.microsoftonline.com/${encodeURIComponent(oauth.tenantId)}/oauth2/v2.0/token`,
{
method: 'POST',
headers: { 'content-type': 'application/x-www-form-urlencoded' },
signal: AbortSignal.timeout(HTTP_TIMEOUT_MS),
body: new URLSearchParams({
grant_type: 'client_credentials',
client_id: oauth.clientId,
client_secret: oauth.clientSecret,
scope: 'https://outlook.office365.com/.default',
}),
},
);
} catch (err) {
throw new TokenError(
err instanceof Error ? err.message : 'microsoft token request failed',
true,
);
}
const body = (await res.json().catch(() => ({}))) as {
access_token?: string;
expires_in?: number;
error_description?: string;
};
if (!res.ok || !body.access_token) {
const retryable = res.status >= 500 || res.status === 429;
// A 4xx is a wrong tenant, client or secret, or a missing grant: retrying will not fix it.
const reason = retryable
? 'microsoft token request failed'
: 'microsoft refused the credentials';
throw new TokenError(
`${reason} (${res.status}): ${body.error_description ?? 'no description'}`,
retryable,
);
}
tokenCache.set(key, {
token: body.access_token,
expiresAt: Date.now() + (body.expires_in ?? 3600) * 1000,
});
return body.access_token;
}
async function smtpAuth(smtp: SmtpConfig) {
if (smtp.auth === 'microsoft365') {
if (!smtp.oauth) throw new TokenError('microsoft 365 app credentials are missing', false);
return {
type: 'OAuth2' as const,
user: smtp.username,
accessToken: await microsoftAccessToken(smtp.oauth),
};
}
return smtp.username ? { user: smtp.username, pass: smtp.password } : undefined;
}
async function sendSmtp(
smtp: SmtpConfig,
message: EmailMessage,
from: string,
): Promise<SendResult> {
// The config stores the timeout in seconds, nodemailer takes milliseconds.
const timeoutMs = smtp.timeout ? smtp.timeout * 1000 : undefined;
let auth: Awaited<ReturnType<typeof smtpAuth>>;
try {
auth = await smtpAuth(smtp);
} catch (err) {
const retryable = err instanceof TokenError ? err.retryable : true;
return { ok: false, retryable, error: err instanceof Error ? err.message : 'smtp auth failed' };
}
const transporter = nodemailer.createTransport({
host: smtp.host,
port: smtp.port ?? (smtp.encryption === 'ssl' ? 465 : 587),
secure: smtp.encryption === 'ssl',
requireTLS: smtp.encryption === 'tls',
auth,
connectionTimeout: timeoutMs,
greetingTimeout: timeoutMs,
socketTimeout: timeoutMs,
});
try {
await transporter.sendMail({
from,
to: message.to,
subject: message.subject,
text: message.text,
html: message.html,
});
return { ok: true };
} catch (err) {
// SMTP 5xx is a permanent rejection; a 4xx code, connection error, or timeout is
// transient and worth retrying.
const code = (err as { responseCode?: number }).responseCode;
const retryable = !(typeof code === 'number' && code >= 500 && code < 600);
return { ok: false, retryable, error: err instanceof Error ? err.message : 'smtp send failed' };
}
}
async function sendResend(
resend: ResendConfig,
message: EmailMessage,
from: string,
): Promise<SendResult> {
try {
const res = await fetch('https://api.resend.com/emails', {
method: 'POST',
headers: {
authorization: `Bearer ${resend.apiKey}`,
'content-type': 'application/json',
...(message.idempotencyKey ? { 'idempotency-key': message.idempotencyKey } : {}),
},
signal: AbortSignal.timeout(HTTP_TIMEOUT_MS),
body: JSON.stringify({
from,
to: [message.to],
subject: message.subject,
text: message.text,
html: message.html,
}),
});
if (res.ok) return { ok: true };
const body = await res.text().catch(() => '');
return {
ok: false,
retryable: res.status === 429 || res.status >= 500,
error: `Resend HTTP ${res.status}: ${body.slice(0, 200)}`,
};
} catch (err) {
return {
ok: false,
retryable: true,
error: err instanceof Error ? err.message : 'resend request failed',
};
}
}
// True when the config has a usable provider. Callers use it to disable features
// that depend on outbound email instead of queuing mail that cannot be sent.
export function hasEmailProvider(config: EmailConfig): boolean {
return smtpReady(config.smtp) || (config.resend.enabled && config.resend.apiKey.length > 0);
}
// Sends one message with the first enabled provider: SMTP wins over Resend when
// both are on.
export async function sendEmail(config: EmailConfig, message: EmailMessage): Promise<SendResult> {
if (!message.to) return { ok: false, retryable: false, error: 'no recipient' };
const { smtp, resend } = config;
if (smtpReady(smtp)) {
const from = fromAddress(config, 'smtp');
if (!from) return { ok: false, retryable: false, error: 'no From address for SMTP' };
return sendSmtp(smtp, message, from);
}
if (resend.enabled && resend.apiKey.length > 0) {
const from = fromAddress(config, 'resend');
if (!from) return { ok: false, retryable: false, error: 'EMAIL_FROM is required for Resend' };
return sendResend(resend, message, from);
}
return { ok: false, retryable: false, error: 'no email provider enabled' };
}
// Wraps a plain-text body (and an optional link) into the text/html pair the
// transport needs, for a message that has no template.
export function emailBody(text: string, url?: string | null): { text: string; html: string } {
const plain = url ? `${text}\n\n${url}` : text;
const body = escapeHtml(text).replace(/\n/g, '<br>');
const link = url ? `<p><a href="${escapeHtml(url)}">${escapeHtml(url)}</a></p>` : '';
return { text: plain, html: `<p>${body}</p>${link}` };
}