import { MailProviderError, type MailAddress, type MailAddressInput, type MailProvider, type SendMailInput, type SendMailResult } from "./types.js"; export const mailjetApiBaseUrl = "https://api.mailjet.com"; const DEFAULT_MAILJET_TIMEOUT_MS = 10_000; const DEFAULT_RESPONSE_BODY_LIMIT_BYTES = 4_096; type Fetch = typeof fetch; type MailjetAddress = { Email: string; Name?: string; }; type MailjetAttachment = { ContentType: string; Filename: string; Base64Content: string; ContentID?: string; }; type MailjetMessage = { From: MailjetAddress; To: MailjetAddress[]; Cc?: MailjetAddress[]; Bcc?: MailjetAddress[]; ReplyTo?: MailjetAddress; Subject?: string; TextPart?: string; HTMLPart?: string; TemplateID?: number; TemplateLanguage?: boolean; Variables?: Record; Attachments?: MailjetAttachment[]; InlinedAttachments?: MailjetAttachment[]; Headers?: Record; CustomCampaign?: string; TrackOpens?: "enabled" | "disabled"; TrackClicks?: "enabled" | "disabled"; CustomID?: string; }; type MailjetSendRequest = { Messages: MailjetMessage[]; SandboxMode?: boolean; }; export type MailMetricsHook = (input: { provider: "mailjet"; status: "delivered" | "failed" }) => void; export type MailjetProviderOptions = { apiKey: string; secretKey: string; fromEmail: string; fromName?: string; baseUrl?: string; fetch?: Fetch; timeoutMs?: number; responseBodyLimitBytes?: number; /** * When true, the request is sent with Mailjet's `SandboxMode` flag so the * payload is validated (auth, addresses, mapping) without actually * delivering mail. Wire this to a staging/test toggle — never enable in * production paths. */ sandbox?: boolean; /** * Optional hook invoked once per send (`status: "delivered"` on HTTP 2xx * with all messages accepted, `"failed"` otherwise). The hook MUST NOT throw * — the provider wraps it in a try/catch so a misbehaving hook can't block * mail delivery. Wire to mail_sent_total in the host app's metrics package. */ onMetric?: MailMetricsHook; }; export type MailjetEnv = Record & { MAILJET_API_KEY?: string; MAILJET_SECRET_KEY?: string; MAILJET_FROM_EMAIL?: string; MAILJET_FROM_NAME?: string; }; export class MailjetProvider implements MailProvider { readonly id = "mailjet" as const; private readonly authorization: string; private readonly defaultFrom: MailAddress; private readonly baseUrl: string; private readonly fetchImpl: Fetch; private readonly timeoutMs: number; private readonly responseBodyLimitBytes: number; private readonly sandbox: boolean; private readonly onMetric: MailMetricsHook | undefined; constructor(options: MailjetProviderOptions) { const apiKey = requireNonEmpty(options.apiKey, "MAILJET_API_KEY"); const secretKey = requireNonEmpty(options.secretKey, "MAILJET_SECRET_KEY"); this.authorization = `Basic ${Buffer.from(`${apiKey}:${secretKey}`, "utf8").toString("base64")}`; this.defaultFrom = { email: requireNonEmpty(options.fromEmail, "MAILJET_FROM_EMAIL"), ...(options.fromName ? { name: options.fromName } : {}), }; this.baseUrl = (options.baseUrl ?? mailjetApiBaseUrl).replace(/\/+$/, ""); this.fetchImpl = options.fetch ?? fetch; this.timeoutMs = normalizePositiveInteger(options.timeoutMs, DEFAULT_MAILJET_TIMEOUT_MS); this.responseBodyLimitBytes = normalizePositiveInteger(options.responseBodyLimitBytes, DEFAULT_RESPONSE_BODY_LIMIT_BYTES); this.sandbox = options.sandbox ?? false; this.onMetric = options.onMetric; } private emitMetric(status: "delivered" | "failed"): void { if (!this.onMetric) return; try { this.onMetric({ provider: "mailjet", status }); } catch { // Metric hook must never abort the send flow. } } async send(input: SendMailInput): Promise { const payload = toMailjetSendRequest(input, this.defaultFrom, this.sandbox); let response: Response; try { response = await fetchWithTimeout( this.fetchImpl, `${this.baseUrl}/v3.1/send`, { method: "POST", headers: { Authorization: this.authorization, "Content-Type": "application/json", Accept: "application/json", }, body: JSON.stringify(payload), }, this.timeoutMs, ); } catch (error) { this.emitMetric("failed"); if (isAbortError(error)) { throw new MailProviderError("Mailjet email request timed out.", { provider: this.id }); } throw error; } const responseBody = await parseResponseBody(response, this.responseBodyLimitBytes); if (!response.ok) { this.emitMetric("failed"); throw new MailProviderError(`Mailjet email request failed with ${response.status}.`, { provider: this.id, statusCode: response.status, responseBody, }); } // Mailjet returns HTTP 200 even when individual messages fail; the // per-message Status carries the real outcome. const messages = extractMessages(responseBody); const rejected = messages.find((message) => typeof message.Status === "string" && message.Status.toLowerCase() !== "success"); if (rejected) { this.emitMetric("failed"); throw new MailProviderError("Mailjet rejected at least one message.", { provider: this.id, statusCode: response.status, responseBody, }); } this.emitMetric("delivered"); return { provider: this.id, status: "queued", messageId: extractMessageId(messages), }; } } export function createMailjetProvider(options: MailjetProviderOptions): MailProvider { return new MailjetProvider(options); } export function createMailjetProviderFromEnv(env: MailjetEnv, options?: { onMetric?: MailMetricsHook; sandbox?: boolean }): MailProvider { return new MailjetProvider({ apiKey: requireNonEmpty(env.MAILJET_API_KEY, "MAILJET_API_KEY"), secretKey: requireNonEmpty(env.MAILJET_SECRET_KEY, "MAILJET_SECRET_KEY"), fromEmail: requireNonEmpty(env.MAILJET_FROM_EMAIL, "MAILJET_FROM_EMAIL"), fromName: env.MAILJET_FROM_NAME, ...(options?.onMetric ? { onMetric: options.onMetric } : {}), ...(options?.sandbox ? { sandbox: options.sandbox } : {}), }); } function toMailjetSendRequest(input: SendMailInput, defaultFrom: MailAddress, sandbox: boolean): MailjetSendRequest { if (input.to.length === 0) { throw new MailProviderError("At least one recipient is required.", { provider: "mailjet" }); } if (!input.text && !input.html && !input.templateId) { throw new MailProviderError("Email text, html or templateId is required.", { provider: "mailjet" }); } const template = normalizeTemplateId(input.templateId); const { attachments, inlined } = normalizeAttachments(input.attachments); const headers = buildHeaders(input); const baseMessage = compactObject({ From: normalizeAddress(input.from ?? defaultFrom), To: [], Cc: input.cc?.map(normalizeAddress), Bcc: input.bcc?.map(normalizeAddress), ReplyTo: input.replyTo ? normalizeAddress(input.replyTo) : undefined, Subject: input.subject, TextPart: input.text, HTMLPart: input.html, TemplateID: template, TemplateLanguage: template !== undefined ? true : undefined, Attachments: attachments, InlinedAttachments: inlined, Headers: headers, CustomCampaign: input.tags?.[0], TrackOpens: toTrackingFlag(input.settings?.trackOpens), TrackClicks: toTrackingFlag(input.settings?.trackClicks), CustomID: normalizeCustomId(input.idempotencyKey), }); const personalization = new Map((input.personalization ?? []).map((entry) => [entry.email, entry.data])); let messages: MailjetMessage[]; if (personalization.size > 1) { // Per-recipient Variables require one Mailjet message each. Cc/Bcc are // attached only to the first message so shared recipients aren't copied // once per personalized message. messages = input.to.map((addr, index) => { const recipient = normalizeAddress(addr); const variables = personalization.get(recipient.Email); return compactObject({ ...baseMessage, ...(index > 0 ? { Cc: undefined, Bcc: undefined } : {}), To: [recipient], Variables: variables, }); }); } else { messages = [ compactObject({ ...baseMessage, To: input.to.map(normalizeAddress), Variables: input.personalization?.[0]?.data, }), ]; } return compactObject({ Messages: messages, SandboxMode: sandbox ? true : undefined, }); } function normalizeAddress(address: MailAddressInput): MailjetAddress { if (typeof address === "string") { return { Email: address }; } return compactObject({ Email: address.email, Name: address.name, }); } function normalizeTemplateId(templateId: string | undefined): number | undefined { if (templateId === undefined) { return undefined; } const numeric = Number(templateId); if (!Number.isFinite(numeric)) { throw new MailProviderError("Mailjet TemplateID must be numeric.", { provider: "mailjet" }); } return numeric; } function normalizeAttachments(attachments: SendMailInput["attachments"]): { attachments?: MailjetAttachment[]; inlined?: MailjetAttachment[] } { if (!attachments?.length) { return {}; } const regular: MailjetAttachment[] = []; const inlined: MailjetAttachment[] = []; for (const attachment of attachments) { const mapped = compactObject({ ContentType: guessContentType(attachment.filename), Filename: attachment.filename, Base64Content: attachment.content, ContentID: attachment.disposition === "inline" ? attachment.id ?? attachment.filename : undefined, }); if (attachment.disposition === "inline") { inlined.push(mapped); } else { regular.push(mapped); } } return { ...(regular.length ? { attachments: regular } : {}), ...(inlined.length ? { inlined } : {}), }; } function buildHeaders(input: SendMailInput): Record | undefined { const headers: Record = {}; for (const header of input.headers ?? []) { headers[header.name] = header.value; } if (input.inReplyTo) { headers["In-Reply-To"] = input.inReplyTo; } if (input.references?.length) { headers["References"] = input.references.join(" "); } if (input.listUnsubscribe) { headers["List-Unsubscribe"] = input.listUnsubscribe; } if (input.precedenceBulk) { headers["Precedence"] = "bulk"; } return Object.keys(headers).length > 0 ? headers : undefined; } function toTrackingFlag(value: boolean | undefined): "enabled" | "disabled" | undefined { if (value === undefined) { return undefined; } return value ? "enabled" : "disabled"; } function normalizeCustomId(idempotencyKey: string | undefined): string | undefined { if (!idempotencyKey) { return undefined; } // Mailjet caps CustomID at 100 characters. return idempotencyKey.slice(0, 100); } type MailjetResponseMessage = { Status?: string; To?: Array<{ MessageUUID?: string; MessageID?: number; MessageHref?: string }>; }; function extractMessages(responseBody: unknown): MailjetResponseMessage[] { if (responseBody && typeof responseBody === "object" && "Messages" in responseBody) { const messages = (responseBody as { Messages?: unknown }).Messages; if (Array.isArray(messages)) { return messages as MailjetResponseMessage[]; } } return []; } function extractMessageId(messages: MailjetResponseMessage[]): string | undefined { const recipient = messages[0]?.To?.[0]; if (!recipient) { return undefined; } return recipient.MessageUUID ?? (recipient.MessageID !== undefined ? String(recipient.MessageID) : undefined); } function guessContentType(filename: string): string { const extension = filename.includes(".") ? filename.slice(filename.lastIndexOf(".") + 1).toLowerCase() : ""; return CONTENT_TYPE_BY_EXTENSION[extension] ?? "application/octet-stream"; } const CONTENT_TYPE_BY_EXTENSION: Record = { pdf: "application/pdf", png: "image/png", jpg: "image/jpeg", jpeg: "image/jpeg", gif: "image/gif", svg: "image/svg+xml", csv: "text/csv", txt: "text/plain", html: "text/html", ics: "text/calendar", json: "application/json", xml: "application/xml", zip: "application/zip", doc: "application/msword", docx: "application/vnd.openxmlformats-officedocument.wordprocessingml.document", xls: "application/vnd.ms-excel", xlsx: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet", }; function requireNonEmpty(value: string | undefined, name: string): string { if (!value?.trim()) { throw new MailProviderError(`${name} is required for Mailjet email delivery.`, { provider: "mailjet" }); } return value; } function compactObject>(value: T): T { return Object.fromEntries(Object.entries(value).filter(([, entry]) => entry !== undefined)) as T; } async function parseResponseBody(response: Response, limitBytes: number): Promise { const text = await readLimitedResponseText(response, limitBytes); if (!text) { return undefined; } try { return JSON.parse(text); } catch { return text; } } async function fetchWithTimeout(fetchImpl: Fetch, input: Parameters[0], init: RequestInit, timeoutMs: number): Promise { const controller = new AbortController(); const timeout = setTimeout(() => controller.abort(), timeoutMs); try { return await fetchImpl(input, { ...init, signal: controller.signal }); } finally { clearTimeout(timeout); } } async function readLimitedResponseText(response: Response, limitBytes: number): Promise { if (!response.body) { return ""; } const reader = response.body.getReader(); const decoder = new TextDecoder(); const chunks: string[] = []; let bytes = 0; while (bytes < limitBytes) { const result = await reader.read(); if (result.done) { chunks.push(decoder.decode()); return chunks.join(""); } const chunk = result.value; const remaining = limitBytes - bytes; const slice = chunk.byteLength > remaining ? chunk.slice(0, remaining) : chunk; chunks.push(decoder.decode(slice, { stream: chunk.byteLength <= remaining })); bytes += slice.byteLength; if (chunk.byteLength > remaining) { await reader.cancel(); break; } } chunks.push(decoder.decode()); return chunks.join(""); } function normalizePositiveInteger(value: number | undefined, fallback: number): number { return typeof value === "number" && Number.isSafeInteger(value) && value > 0 ? value : fallback; } function isAbortError(error: unknown) { return error instanceof Error && error.name === "AbortError"; }