@flink-app/email-plugin 2.0.0-alpha.110 → 2.0.0-alpha.112

package/CHANGELOG.md

@@ -1,5 +1,28 @@
 # @flink-app/email-plugin
 
+## 2.0.0-alpha.112
+
+### Patch Changes
+
+-   Updated dependencies [2e21643]
+    -   @flink-app/flink@2.0.0-alpha.112
+
+## 2.0.0-alpha.111
+
+### Minor Changes
+
+-   00246e8: feat(email-plugin): add MailerSend provider
+
+    Adds `mailersendClient` to `@flink-app/email-plugin`, alongside the existing SendGrid, SMTP, Flowmailer, AWS SES and Postmark clients. Configure with `emailPlugin({ client: new mailersendClient({ apiKey }) })`.
+
+    -   New `emailMailersend` type: addresses as plain strings, `"Name <email>"` strings or `{ email, name }` objects; supports `templateId`, `personalization`, `tags`, inline/regular base64 attachments and `sendAt`
+    -   `sendEmail()` returns rich results (`messageId`, HTTP status and error details)
+    -   Optional `defaultFrom` and `baseUrl` client options
+
+### Patch Changes
+
+-   @flink-app/flink@2.0.0-alpha.111
+
 ## 2.0.0-alpha.110
 
 ### Patch Changes

package/dist/index.d.ts

@@ -5,9 +5,12 @@ export { smtpClient } from "./smtpClient";
 export { flowMailerClient } from "./flowmailerClient";
 export { sesClient } from "./sesClient";
 export { postmarkClient } from "./postmarkClient";
+export { mailersendClient, toMailersendAddress } from "./mailersendClient";
+export type { mailersendClientOptions, MailersendResult } from "./mailersendClient";
 export type { email } from "./schemas/email";
 export type { emailSes } from "./schemas/emailSes";
 export type { emailPostmark, PostmarkAttachment } from "./schemas/emailPostmark";
+export type { emailMailersend, MailersendAddress, MailersendAttachment, MailersendPersonalization, } from "./schemas/emailMailersend";
 export * from "./ses-types";
 export type emailPluginOptions = {
     /**

package/dist/index.js

@@ -14,7 +14,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.emailPlugin = exports.postmarkClient = exports.sesClient = exports.flowMailerClient = exports.smtpClient = exports.sendgridClient = void 0;
+exports.emailPlugin = exports.toMailersendAddress = exports.mailersendClient = exports.postmarkClient = exports.sesClient = exports.flowMailerClient = exports.smtpClient = exports.sendgridClient = void 0;
 var sendgridClient_1 = require("./sendgridClient");
 Object.defineProperty(exports, "sendgridClient", { enumerable: true, get: function () { return sendgridClient_1.sendgridClient; } });
 var smtpClient_1 = require("./smtpClient");
@@ -25,6 +25,9 @@ var sesClient_1 = require("./sesClient");
 Object.defineProperty(exports, "sesClient", { enumerable: true, get: function () { return sesClient_1.sesClient; } });
 var postmarkClient_1 = require("./postmarkClient");
 Object.defineProperty(exports, "postmarkClient", { enumerable: true, get: function () { return postmarkClient_1.postmarkClient; } });
+var mailersendClient_1 = require("./mailersendClient");
+Object.defineProperty(exports, "mailersendClient", { enumerable: true, get: function () { return mailersendClient_1.mailersendClient; } });
+Object.defineProperty(exports, "toMailersendAddress", { enumerable: true, get: function () { return mailersendClient_1.toMailersendAddress; } });
 __exportStar(require("./ses-types"), exports);
 var emailPlugin = function (options) {
     return {

package/dist/mailersendClient.d.ts

@@ -0,0 +1,61 @@
+import { AxiosInstance } from "axios";
+import { client } from "./schemas/client";
+import { emailMailersend as email, MailersendAddress } from "./schemas/emailMailersend";
+export interface mailersendClientOptions {
+    /**
+     * MailerSend API token
+     */
+    apiKey: string;
+    /**
+     * Default "from" address when not specified per-email
+     */
+    defaultFrom?: MailersendAddress;
+    /**
+     * Override API base url, defaults to "https://api.mailersend.com/v1"
+     */
+    baseUrl?: string;
+}
+export interface MailersendResult {
+    success: boolean;
+    /**
+     * Message id returned by MailerSend (from the `x-message-id` response header)
+     */
+    messageId?: string;
+    error?: {
+        /**
+         * HTTP status code from MailerSend, if the request reached the API
+         */
+        status?: number;
+        message: string;
+        /**
+         * Raw error body returned by MailerSend, if any
+         */
+        details?: any;
+    };
+}
+type MailersendAddressPayload = {
+    email: string;
+    name?: string;
+};
+/**
+ * Parse an address string such as "Jane Doe <jane@example.com>" into
+ * MailerSend's `{ email, name }` shape. Plain addresses are passed through.
+ */
+export declare function toMailersendAddress(address: MailersendAddress): MailersendAddressPayload;
+export declare class mailersendClient implements client {
+    private http;
+    private defaultFrom?;
+    constructor(options: mailersendClientOptions, http?: AxiosInstance);
+    /**
+     * Send an email via MailerSend. Implements the base `client` interface.
+     * Returns `true` on success, `false` on failure.
+     * For richer results (messageId, error details), use `sendEmail()` instead.
+     */
+    send(email: email): Promise<boolean>;
+    /**
+     * Send an email via MailerSend with rich result including messageId and error details.
+     */
+    sendEmail(email: email): Promise<MailersendResult>;
+    private buildPayload;
+}
+export {};

package/dist/mailersendClient.js

@@ -0,0 +1,179 @@
+"use strict";
+var __assign = (this && this.__assign) || function () {
+    __assign = Object.assign || function(t) {
+        for (var s, i = 1, n = arguments.length; i < n; i++) {
+            s = arguments[i];
+            for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p))
+                t[p] = s[p];
+        }
+        return t;
+    };
+    return __assign.apply(this, arguments);
+};
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __generator = (this && this.__generator) || function (thisArg, body) {
+    var _ = { label: 0, sent: function() { if (t[0] & 1) throw t[1]; return t[1]; }, trys: [], ops: [] }, f, y, t, g = Object.create((typeof Iterator === "function" ? Iterator : Object).prototype);
+    return g.next = verb(0), g["throw"] = verb(1), g["return"] = verb(2), typeof Symbol === "function" && (g[Symbol.iterator] = function() { return this; }), g;
+    function verb(n) { return function (v) { return step([n, v]); }; }
+    function step(op) {
+        if (f) throw new TypeError("Generator is already executing.");
+        while (g && (g = 0, op[0] && (_ = 0)), _) try {
+            if (f = 1, y && (t = op[0] & 2 ? y["return"] : op[0] ? y["throw"] || ((t = y["return"]) && t.call(y), 0) : y.next) && !(t = t.call(y, op[1])).done) return t;
+            if (y = 0, t) op = [op[0] & 2, t.value];
+            switch (op[0]) {
+                case 0: case 1: t = op; break;
+                case 4: _.label++; return { value: op[1], done: false };
+                case 5: _.label++; y = op[1]; op = [0]; continue;
+                case 7: op = _.ops.pop(); _.trys.pop(); continue;
+                default:
+                    if (!(t = _.trys, t = t.length > 0 && t[t.length - 1]) && (op[0] === 6 || op[0] === 2)) { _ = 0; continue; }
+                    if (op[0] === 3 && (!t || (op[1] > t[0] && op[1] < t[3]))) { _.label = op[1]; break; }
+                    if (op[0] === 6 && _.label < t[1]) { _.label = t[1]; t = op; break; }
+                    if (t && _.label < t[2]) { _.label = t[2]; _.ops.push(op); break; }
+                    if (t[2]) _.ops.pop();
+                    _.trys.pop(); continue;
+            }
+            op = body.call(thisArg, _);
+        } catch (e) { op = [6, e]; y = 0; } finally { f = t = 0; }
+        if (op[0] & 5) throw op[1]; return { value: op[0] ? op[1] : void 0, done: true };
+    }
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.mailersendClient = void 0;
+exports.toMailersendAddress = toMailersendAddress;
+var axios_1 = __importDefault(require("axios"));
+/**
+ * Parse an address string such as "Jane Doe <jane@example.com>" into
+ * MailerSend's `{ email, name }` shape. Plain addresses are passed through.
+ */
+function toMailersendAddress(address) {
+    if (typeof address !== "string") {
+        return address.name ? { email: address.email, name: address.name } : { email: address.email };
+    }
+    var match = address.trim().match(/^(.*?)\s*<([^<>]+)>$/);
+    if (match) {
+        var name = match[1].replace(/^"|"$/g, "").trim();
+        return name ? { email: match[2].trim(), name: name } : { email: match[2].trim() };
+    }
+    return { email: address.trim() };
+}
+var mailersendClient = /** @class */ (function () {
+    function mailersendClient(options, http) {
+        var _a;
+        this.defaultFrom = options.defaultFrom;
+        this.http =
+            http !== null && http !== void 0 ? http : axios_1.default.create({
+                baseURL: (_a = options.baseUrl) !== null && _a !== void 0 ? _a : "https://api.mailersend.com/v1",
+                headers: {
+                    Authorization: "Bearer ".concat(options.apiKey),
+                    "Content-Type": "application/json",
+                    "X-Requested-With": "XMLHttpRequest",
+                },
+            });
+    }
+    /**
+     * Send an email via MailerSend. Implements the base `client` interface.
+     * Returns `true` on success, `false` on failure.
+     * For richer results (messageId, error details), use `sendEmail()` instead.
+     */
+    mailersendClient.prototype.send = function (email) {
+        return __awaiter(this, void 0, void 0, function () {
+            var result;
+            return __generator(this, function (_a) {
+                switch (_a.label) {
+                    case 0: return [4 /*yield*/, this.sendEmail(email)];
+                    case 1:
+                        result = _a.sent();
+                        return [2 /*return*/, result.success];
+                }
+            });
+        });
+    };
+    /**
+     * Send an email via MailerSend with rich result including messageId and error details.
+     */
+    mailersendClient.prototype.sendEmail = function (email) {
+        return __awaiter(this, void 0, void 0, function () {
+            var from, payload, resp, messageId, ex_1, status, details, message;
+            var _a, _b, _c;
+            return __generator(this, function (_d) {
+                switch (_d.label) {
+                    case 0:
+                        from = email.from || this.defaultFrom;
+                        if (!from) {
+                            return [2 /*return*/, {
+                                    success: false,
+                                    error: {
+                                        message: "No 'from' address specified. Set it on the email or use defaultFrom in mailersendClientOptions.",
+                                    },
+                                }];
+                        }
+                        payload = this.buildPayload(email, from);
+                        _d.label = 1;
+                    case 1:
+                        _d.trys.push([1, 3, , 4]);
+                        return [4 /*yield*/, this.http.post("/email", payload)];
+                    case 2:
+                        resp = _d.sent();
+                        messageId = (_a = resp.headers) === null || _a === void 0 ? void 0 : _a["x-message-id"];
+                        return [2 /*return*/, { success: true, messageId: messageId }];
+                    case 3:
+                        ex_1 = _d.sent();
+                        status = (_b = ex_1 === null || ex_1 === void 0 ? void 0 : ex_1.response) === null || _b === void 0 ? void 0 : _b.status;
+                        details = (_c = ex_1 === null || ex_1 === void 0 ? void 0 : ex_1.response) === null || _c === void 0 ? void 0 : _c.data;
+                        message = (details === null || details === void 0 ? void 0 : details.message) || (ex_1 === null || ex_1 === void 0 ? void 0 : ex_1.message) || "Unknown error";
+                        console.log(JSON.stringify({ error: "MailerSend send failed", status: status, message: message, details: details }));
+                        return [2 /*return*/, { success: false, error: { status: status, message: message, details: details } }];
+                    case 4: return [2 /*return*/];
+                }
+            });
+        });
+    };
+    mailersendClient.prototype.buildPayload = function (email, from) {
+        var _a, _b, _c, _d, _e;
+        var payload = {
+            from: toMailersendAddress(from),
+            to: email.to.map(toMailersendAddress),
+        };
+        if ((_a = email.cc) === null || _a === void 0 ? void 0 : _a.length)
+            payload.cc = email.cc.map(toMailersendAddress);
+        if ((_b = email.bcc) === null || _b === void 0 ? void 0 : _b.length)
+            payload.bcc = email.bcc.map(toMailersendAddress);
+        if (email.replyTo)
+            payload.reply_to = toMailersendAddress(email.replyTo);
+        if (email.subject !== undefined)
+            payload.subject = email.subject;
+        if (email.text !== undefined)
+            payload.text = email.text;
+        if (email.html !== undefined)
+            payload.html = email.html;
+        if (email.templateId)
+            payload.template_id = email.templateId;
+        if ((_c = email.personalization) === null || _c === void 0 ? void 0 : _c.length)
+            payload.personalization = email.personalization;
+        if ((_d = email.tags) === null || _d === void 0 ? void 0 : _d.length)
+            payload.tags = email.tags;
+        if ((_e = email.attachments) === null || _e === void 0 ? void 0 : _e.length) {
+            payload.attachments = email.attachments.map(function (a) {
+                var _a;
+                return (__assign({ content: a.content, filename: a.filename, disposition: (_a = a.disposition) !== null && _a !== void 0 ? _a : "attachment" }, (a.id ? { id: a.id } : {})));
+            });
+        }
+        if (email.sendAt !== undefined)
+            payload.send_at = email.sendAt;
+        return payload;
+    };
+    return mailersendClient;
+}());
+exports.mailersendClient = mailersendClient;

package/dist/schemas/client.d.ts

@@ -1,8 +1,9 @@
 import { email } from "./email";
 import { emailFlowmailer } from "./emailFlowmailer";
+import { emailMailersend } from "./emailMailersend";
 import { emailPostmark } from "./emailPostmark";
 import { emailSendgrid } from "./emailSendgrid";
 import { emailSes } from "./emailSes";
 export interface client {
-    send(email: email | emailSendgrid | emailFlowmailer | emailSes | emailPostmark): Promise<boolean>;
+    send(email: email | emailSendgrid | emailFlowmailer | emailSes | emailPostmark | emailMailersend): Promise<boolean>;
 }

package/dist/schemas/emailMailersend.d.ts

@@ -0,0 +1,96 @@
+/**
+ * An email address, either as a plain string ("user@example.com" or
+ * "Display Name <user@example.com>") or as an object with email and optional name.
+ */
+export type MailersendAddress = string | {
+    email: string;
+    name?: string;
+};
+export interface MailersendAttachment {
+    /**
+     * Base64 encoded content
+     */
+    content: string;
+    /**
+     * Filename shown to recipient
+     */
+    filename: string;
+    /**
+     * "attachment" (default) or "inline". Inline attachments can be referenced
+     * from HTML via the `id`, e.g. `<img src="cid:image1">`
+     */
+    disposition?: "attachment" | "inline";
+    /**
+     * Content-ID used to reference inline attachments from the HTML body
+     */
+    id?: string;
+}
+export interface MailersendPersonalization {
+    /**
+     * Recipient email address this personalization data applies to
+     */
+    email: string;
+    /**
+     * Variables available to the template / `{{ var }}` substitutions
+     */
+    data: Record<string, any>;
+}
+type emailMailersendBase = {
+    /**
+     * From address used to send the email
+     */
+    from: MailersendAddress;
+    /**
+     * Email addresses to send to
+     */
+    to: MailersendAddress[];
+    /**
+     * CC addresses
+     */
+    cc?: MailersendAddress[];
+    /**
+     * BCC addresses
+     */
+    bcc?: MailersendAddress[];
+    /**
+     * Reply-to address
+     */
+    replyTo?: MailersendAddress;
+    /**
+     * MailerSend tags attached to the message
+     */
+    tags?: string[];
+    /**
+     * Per-recipient template/substitution variables
+     */
+    personalization?: MailersendPersonalization[];
+    /**
+     * File attachments
+     */
+    attachments?: MailersendAttachment[];
+    /**
+     * Unix timestamp (seconds) to schedule the email for later delivery (max 72h ahead)
+     */
+    sendAt?: number;
+};
+export type emailMailersend = emailMailersendBase & ({
+    subject: string;
+    text: string;
+    html?: string;
+    templateId?: string;
+} | {
+    subject: string;
+    html: string;
+    text?: string;
+    templateId?: string;
+} | {
+    /**
+     * MailerSend template id. When set, subject/text/html may be omitted
+     * and are taken from the template (unless overridden here).
+     */
+    templateId: string;
+    subject?: string;
+    text?: string;
+    html?: string;
+});
+export {};

package/dist/schemas/emailMailersend.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@flink-app/email-plugin",
-  "version": "2.0.0-alpha.110",
-  "description": "Flink plugin that provides multi-provider email sending capabilities with support for SendGrid, SMTP, Flowmailer, AWS SES, and Postmark",
+  "version": "2.0.0-alpha.112",
+  "description": "Flink plugin that provides multi-provider email sending capabilities with support for SendGrid, SMTP, Flowmailer, AWS SES, Postmark, and MailerSend",
   "author": "johan@frost.se",
   "publishConfig": {
     "access": "public"
@@ -21,11 +21,11 @@
   "devDependencies": {
     "@types/jasmine": "^3.7.1",
     "@types/node": "22.13.10",
-    "@flink-app/flink": "2.0.0-alpha.110"
+    "@flink-app/flink": "2.0.0-alpha.112"
   },
   "gitHead": "4243e3b3cd6d4e1ca001a61baa8436bf2bbe4113",
   "peerDependencies": {
-    "@flink-app/flink": ">=2.0.0-alpha.110"
+    "@flink-app/flink": ">=2.0.0-alpha.112"
   },
   "scripts": {
     "test": "jasmine-ts --config=./spec/support/jasmine.json",

package/readme.md

@@ -1,6 +1,6 @@
 # Email Plugin
 
-A Flink plugin that provides multi-provider email sending capabilities with support for SendGrid, SMTP, Flowmailer, AWS SES, and Postmark.
+A Flink plugin that provides multi-provider email sending capabilities with support for SendGrid, SMTP, Flowmailer, AWS SES, Postmark, and MailerSend.
 
 ## Installation
 
@@ -12,7 +12,7 @@ npm install @flink-app/email-plugin
 
 ## Configuration
 
-The email plugin supports five different email providers through a unified client interface:
+The email plugin supports six different email providers through a unified client interface:
 
 ### Option 1: SendGrid
 
@@ -217,6 +217,94 @@ interface PostmarkAttachment {
 }
 ```
 
+### Option 6: MailerSend
+
+Configure the plugin with [MailerSend](https://www.mailersend.com/):
+
+```typescript
+import { emailPlugin, mailersendClient } from "@flink-app/email-plugin";
+
+function start() {
+  new FlinkApp<AppContext>({
+    name: "My app",
+    plugins: [
+      emailPlugin({
+        client: new mailersendClient({
+          apiKey: process.env.MAILERSEND_API_KEY!,
+          defaultFrom: "noreply@example.com", // optional
+        })
+      })
+    ],
+  }).start();
+}
+```
+
+**MailerSend Client Options:**
+
+```typescript
+interface mailersendClientOptions {
+  apiKey: string;                 // MailerSend API token
+  defaultFrom?: MailersendAddress; // Used when email.from is empty
+  baseUrl?: string;               // Defaults to "https://api.mailersend.com/v1"
+}
+```
+
+**MailerSend Email Type:**
+
+```typescript
+type MailersendAddress = string | { email: string; name?: string };
+// Strings may be plain ("user@example.com") or "Display Name <user@example.com>"
+
+type emailMailersend = {
+  from: MailersendAddress;
+  to: MailersendAddress[];
+  cc?: MailersendAddress[];
+  bcc?: MailersendAddress[];
+  replyTo?: MailersendAddress;
+  tags?: string[];                              // MailerSend tags
+  personalization?: MailersendPersonalization[]; // Per-recipient template variables
+  attachments?: MailersendAttachment[];
+  sendAt?: number;                              // Unix timestamp for scheduled delivery
+} & (
+  | { subject: string; text: string; html?: string; templateId?: string }
+  | { subject: string; html: string; text?: string; templateId?: string }
+  | { templateId: string; subject?: string; text?: string; html?: string }
+);
+
+interface MailersendAttachment {
+  content: string;                      // Base64 encoded
+  filename: string;
+  disposition?: "attachment" | "inline"; // Defaults to "attachment"
+  id?: string;                           // Content-ID for inline images
+}
+
+interface MailersendPersonalization {
+  email: string;             // Recipient the data applies to
+  data: Record<string, any>; // Template variables
+}
+```
+
+**Templates and rich results:**
+
+```typescript
+import { mailersendClient } from "@flink-app/email-plugin";
+const mailersend = ctx.plugins.emailPlugin.client as mailersendClient;
+
+// Send using a MailerSend template with per-recipient variables
+const result = await mailersend.sendEmail({
+  from: { email: "noreply@example.com", name: "My App" },
+  to: ["user@example.com"],
+  templateId: "3z0vklo7x1pg7qrx",
+  personalization: [{ email: "user@example.com", data: { name: "Jane" } }],
+});
+
+if (result.success) {
+  console.log("Sent:", result.messageId);
+} else {
+  console.error(`Failed: ${result.error?.status} - ${result.error?.message}`);
+}
+```
+
 ## TypeScript Setup
 
 Add the plugin context to your app's context type (usually in `Ctx.ts`):
@@ -405,7 +493,7 @@ All email clients implement this unified interface:
 
 ```typescript
 interface client {
-  send(email: email | emailSendgrid | emailFlowmailer | emailSes | emailPostmark): Promise<boolean>;
+  send(email: email | emailSendgrid | emailFlowmailer | emailSes | emailPostmark | emailMailersend): Promise<boolean>;
 }
 ```
 

package/spec/mailersendClient.spec.ts

@@ -0,0 +1,191 @@
+import { mailersendClient, toMailersendAddress } from "../src/mailersendClient";
+
+function createMockHttp(overrides?: { response?: any; error?: any }) {
+  return {
+    post: jasmine.createSpy("post").and.callFake(async () => {
+      if (overrides?.error) throw overrides.error;
+      return (
+        overrides?.response ?? {
+          status: 202,
+          headers: { "x-message-id": "msg-123" },
+          data: "",
+        }
+      );
+    }),
+  } as any;
+}
+
+describe("mailersendClient", () => {
+  describe("toMailersendAddress()", () => {
+    it("should pass through plain email strings", () => {
+      expect(toMailersendAddress("a@example.com")).toEqual({ email: "a@example.com" });
+    });
+
+    it("should parse 'Name <email>' strings", () => {
+      expect(toMailersendAddress("Jane Doe <jane@example.com>")).toEqual({
+        email: "jane@example.com",
+        name: "Jane Doe",
+      });
+      expect(toMailersendAddress('"Jane Doe" <jane@example.com>')).toEqual({
+        email: "jane@example.com",
+        name: "Jane Doe",
+      });
+    });
+
+    it("should pass through address objects", () => {
+      expect(toMailersendAddress({ email: "a@example.com", name: "A" })).toEqual({
+        email: "a@example.com",
+        name: "A",
+      });
+      expect(toMailersendAddress({ email: "a@example.com" })).toEqual({ email: "a@example.com" });
+    });
+  });
+
+  describe("send()", () => {
+    it("should POST a mapped payload to /email and return true", async () => {
+      const http = createMockHttp();
+      const client = new mailersendClient({ apiKey: "key" }, http);
+
+      const result = await client.send({
+        from: "Sender <sender@example.com>",
+        to: ["recipient@example.com", { email: "other@example.com", name: "Other" }],
+        cc: ["cc@example.com"],
+        bcc: ["bcc@example.com"],
+        replyTo: "reply@example.com",
+        subject: "Test",
+        text: "Hello",
+        html: "<p>Hello</p>",
+        tags: ["welcome"],
+        attachments: [{ content: "YmFzZTY0", filename: "file.txt" }],
+      });
+
+      expect(result).toBe(true);
+      expect(http.post).toHaveBeenCalledTimes(1);
+      const [url, payload] = http.post.calls.first().args;
+      expect(url).toBe("/email");
+      expect(payload).toEqual({
+        from: { email: "sender@example.com", name: "Sender" },
+        to: [{ email: "recipient@example.com" }, { email: "other@example.com", name: "Other" }],
+        cc: [{ email: "cc@example.com" }],
+        bcc: [{ email: "bcc@example.com" }],
+        reply_to: { email: "reply@example.com" },
+        subject: "Test",
+        text: "Hello",
+        html: "<p>Hello</p>",
+        tags: ["welcome"],
+        attachments: [{ content: "YmFzZTY0", filename: "file.txt", disposition: "attachment" }],
+      });
+    });
+
+    it("should send template emails with personalization", async () => {
+      const http = createMockHttp();
+      const client = new mailersendClient({ apiKey: "key" }, http);
+
+      await client.send({
+        from: "sender@example.com",
+        to: ["recipient@example.com"],
+        templateId: "tpl-1",
+        personalization: [{ email: "recipient@example.com", data: { name: "Jane" } }],
+      });
+
+      const payload = http.post.calls.first().args[1];
+      expect(payload.template_id).toBe("tpl-1");
+      expect(payload.personalization).toEqual([
+        { email: "recipient@example.com", data: { name: "Jane" } },
+      ]);
+      expect(payload.subject).toBeUndefined();
+      expect(payload.text).toBeUndefined();
+      expect(payload.html).toBeUndefined();
+    });
+
+    it("should use defaultFrom when email has no from", async () => {
+      const http = createMockHttp();
+      const client = new mailersendClient(
+        { apiKey: "key", defaultFrom: { email: "default@example.com", name: "Default" } },
+        http
+      );
+
+      await client.send({
+        from: "",
+        to: ["recipient@example.com"],
+        subject: "Test",
+        text: "Hello",
+      });
+
+      expect(http.post.calls.first().args[1].from).toEqual({
+        email: "default@example.com",
+        name: "Default",
+      });
+    });
+
+    it("should return false without calling the API when no from is available", async () => {
+      const http = createMockHttp();
+      const client = new mailersendClient({ apiKey: "key" }, http);
+
+      const result = await client.send({
+        from: "",
+        to: ["recipient@example.com"],
+        subject: "Test",
+        text: "Hello",
+      });
+
+      expect(result).toBe(false);
+      expect(http.post).not.toHaveBeenCalled();
+    });
+
+    it("should return false on API error", async () => {
+      const http = createMockHttp({
+        error: { response: { status: 422, data: { message: "The from.email must be verified." } } },
+      });
+      const client = new mailersendClient({ apiKey: "key" }, http);
+
+      const result = await client.send({
+        from: "sender@example.com",
+        to: ["recipient@example.com"],
+        subject: "Test",
+        text: "Hello",
+      });
+
+      expect(result).toBe(false);
+    });
+  });
+
+  describe("sendEmail()", () => {
+    it("should return messageId from response header on success", async () => {
+      const http = createMockHttp({
+        response: { status: 202, headers: { "x-message-id": "abc-987" }, data: "" },
+      });
+      const client = new mailersendClient({ apiKey: "key" }, http);
+
+      const result = await client.sendEmail({
+        from: "sender@example.com",
+        to: ["recipient@example.com"],
+        subject: "Test",
+        text: "Hello",
+      });
+
+      expect(result).toEqual({ success: true, messageId: "abc-987" });
+    });
+
+    it("should return error details on failure", async () => {
+      const http = createMockHttp({
+        error: {
+          response: { status: 422, data: { message: "Validation failed", errors: { to: ["bad"] } } },
+        },
+      });
+      const client = new mailersendClient({ apiKey: "key" }, http);
+
+      const result = await client.sendEmail({
+        from: "sender@example.com",
+        to: ["recipient@example.com"],
+        subject: "Test",
+        text: "Hello",
+      });
+
+      expect(result.success).toBe(false);
+      expect(result.error?.status).toBe(422);
+      expect(result.error?.message).toBe("Validation failed");
+      expect(result.error?.details).toEqual({ message: "Validation failed", errors: { to: ["bad"] } });
+    });
+  });
+});

package/src/index.ts

@@ -5,9 +5,17 @@ export { smtpClient } from "./smtpClient";
 export { flowMailerClient } from "./flowmailerClient";
 export { sesClient } from "./sesClient";
 export { postmarkClient } from "./postmarkClient";
+export { mailersendClient, toMailersendAddress } from "./mailersendClient";
+export type { mailersendClientOptions, MailersendResult } from "./mailersendClient";
 export type { email } from "./schemas/email";
 export type { emailSes } from "./schemas/emailSes";
 export type { emailPostmark, PostmarkAttachment } from "./schemas/emailPostmark";
+export type {
+  emailMailersend,
+  MailersendAddress,
+  MailersendAttachment,
+  MailersendPersonalization,
+} from "./schemas/emailMailersend";
 export * from "./ses-types";
 
 export type emailPluginOptions = {

package/src/mailersendClient.ts

@@ -0,0 +1,170 @@
+import axios, { AxiosInstance } from "axios";
+import { client } from "./schemas/client";
+import {
+  emailMailersend as email,
+  MailersendAddress,
+} from "./schemas/emailMailersend";
+
+export interface mailersendClientOptions {
+  /**
+   * MailerSend API token
+   */
+  apiKey: string;
+
+  /**
+   * Default "from" address when not specified per-email
+   */
+  defaultFrom?: MailersendAddress;
+
+  /**
+   * Override API base url, defaults to "https://api.mailersend.com/v1"
+   */
+  baseUrl?: string;
+}
+
+export interface MailersendResult {
+  success: boolean;
+  /**
+   * Message id returned by MailerSend (from the `x-message-id` response header)
+   */
+  messageId?: string;
+  error?: {
+    /**
+     * HTTP status code from MailerSend, if the request reached the API
+     */
+    status?: number;
+    message: string;
+    /**
+     * Raw error body returned by MailerSend, if any
+     */
+    details?: any;
+  };
+}
+
+type MailersendAddressPayload = { email: string; name?: string };
+
+type MailersendPayload = {
+  from: MailersendAddressPayload;
+  to: MailersendAddressPayload[];
+  cc?: MailersendAddressPayload[];
+  bcc?: MailersendAddressPayload[];
+  reply_to?: MailersendAddressPayload;
+  subject?: string;
+  text?: string;
+  html?: string;
+  template_id?: string;
+  personalization?: { email: string; data: Record<string, any> }[];
+  tags?: string[];
+  attachments?: {
+    content: string;
+    filename: string;
+    disposition?: "attachment" | "inline";
+    id?: string;
+  }[];
+  send_at?: number;
+};
+
+/**
+ * Parse an address string such as "Jane Doe <jane@example.com>" into
+ * MailerSend's `{ email, name }` shape. Plain addresses are passed through.
+ */
+export function toMailersendAddress(
+  address: MailersendAddress
+): MailersendAddressPayload {
+  if (typeof address !== "string") {
+    return address.name ? { email: address.email, name: address.name } : { email: address.email };
+  }
+  const match = address.trim().match(/^(.*?)\s*<([^<>]+)>$/);
+  if (match) {
+    const name = match[1].replace(/^"|"$/g, "").trim();
+    return name ? { email: match[2].trim(), name } : { email: match[2].trim() };
+  }
+  return { email: address.trim() };
+}
+
+export class mailersendClient implements client {
+  private http: AxiosInstance;
+  private defaultFrom?: MailersendAddress;
+
+  constructor(options: mailersendClientOptions, http?: AxiosInstance) {
+    this.defaultFrom = options.defaultFrom;
+    this.http =
+      http ??
+      axios.create({
+        baseURL: options.baseUrl ?? "https://api.mailersend.com/v1",
+        headers: {
+          Authorization: `Bearer ${options.apiKey}`,
+          "Content-Type": "application/json",
+          "X-Requested-With": "XMLHttpRequest",
+        },
+      });
+  }
+
+  /**
+   * Send an email via MailerSend. Implements the base `client` interface.
+   * Returns `true` on success, `false` on failure.
+   * For richer results (messageId, error details), use `sendEmail()` instead.
+   */
+  async send(email: email): Promise<boolean> {
+    const result = await this.sendEmail(email);
+    return result.success;
+  }
+
+  /**
+   * Send an email via MailerSend with rich result including messageId and error details.
+   */
+  async sendEmail(email: email): Promise<MailersendResult> {
+    const from = email.from || this.defaultFrom;
+    if (!from) {
+      return {
+        success: false,
+        error: {
+          message:
+            "No 'from' address specified. Set it on the email or use defaultFrom in mailersendClientOptions.",
+        },
+      };
+    }
+
+    const payload = this.buildPayload(email, from);
+
+    try {
+      const resp = await this.http.post("/email", payload);
+      const messageId = resp.headers?.["x-message-id"];
+      return { success: true, messageId };
+    } catch (ex: any) {
+      const status: number | undefined = ex?.response?.status;
+      const details = ex?.response?.data;
+      const message: string = details?.message || ex?.message || "Unknown error";
+      console.log(
+        JSON.stringify({ error: "MailerSend send failed", status, message, details })
+      );
+      return { success: false, error: { status, message, details } };
+    }
+  }
+
+  private buildPayload(email: email, from: MailersendAddress): MailersendPayload {
+    const payload: MailersendPayload = {
+      from: toMailersendAddress(from),
+      to: email.to.map(toMailersendAddress),
+    };
+    if (email.cc?.length) payload.cc = email.cc.map(toMailersendAddress);
+    if (email.bcc?.length) payload.bcc = email.bcc.map(toMailersendAddress);
+    if (email.replyTo) payload.reply_to = toMailersendAddress(email.replyTo);
+    if (email.subject !== undefined) payload.subject = email.subject;
+    if (email.text !== undefined) payload.text = email.text;
+    if (email.html !== undefined) payload.html = email.html;
+    if (email.templateId) payload.template_id = email.templateId;
+    if (email.personalization?.length) payload.personalization = email.personalization;
+    if (email.tags?.length) payload.tags = email.tags;
+    if (email.attachments?.length) {
+      payload.attachments = email.attachments.map((a) => ({
+        content: a.content,
+        filename: a.filename,
+        disposition: a.disposition ?? "attachment",
+        ...(a.id ? { id: a.id } : {}),
+      }));
+    }
+    if (email.sendAt !== undefined) payload.send_at = email.sendAt;
+    return payload;
+  }
+}

package/src/schemas/client.ts

@@ -1,9 +1,10 @@
 import { email } from "./email";
 import { emailFlowmailer } from "./emailFlowmailer";
+import { emailMailersend } from "./emailMailersend";
 import { emailPostmark } from "./emailPostmark";
 import { emailSendgrid } from "./emailSendgrid";
 import { emailSes } from "./emailSes";
 
 export interface client {
-  send(email: email | emailSendgrid | emailFlowmailer | emailSes | emailPostmark): Promise<boolean>;
+  send(email: email | emailSendgrid | emailFlowmailer | emailSes | emailPostmark | emailMailersend): Promise<boolean>;
 }

package/src/schemas/emailMailersend.ts

@@ -0,0 +1,103 @@
+/**
+ * An email address, either as a plain string ("user@example.com" or
+ * "Display Name <user@example.com>") or as an object with email and optional name.
+ */
+export type MailersendAddress = string | { email: string; name?: string };
+
+export interface MailersendAttachment {
+  /**
+   * Base64 encoded content
+   */
+  content: string;
+
+  /**
+   * Filename shown to recipient
+   */
+  filename: string;
+
+  /**
+   * "attachment" (default) or "inline". Inline attachments can be referenced
+   * from HTML via the `id`, e.g. `<img src="cid:image1">`
+   */
+  disposition?: "attachment" | "inline";
+
+  /**
+   * Content-ID used to reference inline attachments from the HTML body
+   */
+  id?: string;
+}
+
+export interface MailersendPersonalization {
+  /**
+   * Recipient email address this personalization data applies to
+   */
+  email: string;
+
+  /**
+   * Variables available to the template / `{{ var }}` substitutions
+   */
+  data: Record<string, any>;
+}
+
+type emailMailersendBase = {
+  /**
+   * From address used to send the email
+   */
+  from: MailersendAddress;
+
+  /**
+   * Email addresses to send to
+   */
+  to: MailersendAddress[];
+
+  /**
+   * CC addresses
+   */
+  cc?: MailersendAddress[];
+
+  /**
+   * BCC addresses
+   */
+  bcc?: MailersendAddress[];
+
+  /**
+   * Reply-to address
+   */
+  replyTo?: MailersendAddress;
+
+  /**
+   * MailerSend tags attached to the message
+   */
+  tags?: string[];
+
+  /**
+   * Per-recipient template/substitution variables
+   */
+  personalization?: MailersendPersonalization[];
+
+  /**
+   * File attachments
+   */
+  attachments?: MailersendAttachment[];
+
+  /**
+   * Unix timestamp (seconds) to schedule the email for later delivery (max 72h ahead)
+   */
+  sendAt?: number;
+};
+
+export type emailMailersend = emailMailersendBase &
+  (
+    | { subject: string; text: string; html?: string; templateId?: string }
+    | { subject: string; html: string; text?: string; templateId?: string }
+    | {
+        /**
+         * MailerSend template id. When set, subject/text/html may be omitted
+         * and are taken from the template (unless overridden here).
+         */
+        templateId: string;
+        subject?: string;
+        text?: string;
+        html?: string;
+      }
+  );