MailerSend

Send through the MailerSend Email API with cc/bcc, headers, tags, attachments, and a single reply-to address.

Capabilities

Repeated headers	Idempotency	Scheduling	Personalized
No	`none`	Yes	`expanded`

These values come from the adapter's exported capabilities declaration. The field support matrix covers normalized message fields.

The MailerSend adapter calls the MailerSend Email API with plain fetch. Two quirks to know: MailerSend accepts exactly one reply-to address, and the message id comes back in the x-message-id response header rather than the body.

MailerSend@opencoredev/email-sdk/mailersend

Provider docs

Configure

Create an API token in the MailerSend dashboard and verify the domain you plan to send from.

lib/email.ts

import { createEmailClient } from "@opencoredev/email-sdk";
import { mailersend } from "@opencoredev/email-sdk/mailersend";

export const email = createEmailClient({
  adapters: [mailersend({ apiKey: process.env.MAILERSEND_API_KEY! })],
});

Prop

Type

Send

MailerSend maps cc, bcc, headers, attachments (an attachment's contentId becomes MailerSend's id), and tags (values only). replyTo accepts a single address; two or more throw an EmailValidationError before any request. sendAt maps to send_at (a Unix timestamp in seconds), so MailerSend holds the message until then. It accepts at most 72 hours in the future.

const result = await email.send({
  from: "Acme <hello@acme.com>",
  to: [{ email: "user@example.com", name: "Ada" }],
  replyTo: "support@acme.com",
  subject: "Reset your Acme password",
  html: "<p>Click the link below to choose a new password.</p>",
  tags: [{ name: "type", value: "password-reset" }],
});

console.log(result.id); // MailerSend message id from the x-message-id header

The response id comes from the x-message-id response header, falling back to message_id or id in the body. Use it to look the send up in MailerSend's activity log.

No metadata field

MailerSend has no metadata concept, so metadata on a message throws an EmailValidationError before any request is made. Use tags instead, or pick a metadata-capable adapter. MailerSend also gates custom headers behind its Professional and Enterprise plans.

Verify from the CLI

MAILERSEND_API_KEY="mlsn..." npx --package @opencoredev/email-sdk email-sdk doctor --adapter mailersend

MAILERSEND_API_KEY="mlsn..." npx --package @opencoredev/email-sdk email-sdk send \
  --adapter mailersend \
  --from "Acme <hello@acme.com>" \
  --to user@example.com \
  --subject "MailerSend smoke test" \
  --text "It works" \
  --dry-run

Drop --dry-run for one real send. The token, domain verification, and plan limits only prove themselves against the live API.

Compare MailerSend with other providers

Side-by-side message-field support from the SDK capability matrix, with working code for both adapters:

Frequently asked questions

Does Email SDK support MailerSend?

Yes. Email SDK ships a MailerSend adapter imported from @opencoredev/email-sdk/mailersend. You keep your MailerSend account and credentials; the SDK adds message validation, typed errors, and no-network test adapters around the same send() call used for every other provider.

Which message fields does the MailerSend adapter support?

MailerSend supports CC recipients, BCC recipients, Reply-To address, Custom headers, Attachments, Tags, and Scheduled sending (sendAt). It does not support Metadata; Email SDK rejects a message that uses those fields before any request is made.

Can MailerSend schedule email for later with Email SDK?

Yes. Set sendAt on the message and the MailerSend adapter passes the scheduled time to the provider.

Does the MailerSend adapter support idempotent sends?

No. MailerSend has no provider-side idempotency, so a retried send can be delivered twice. Deduplicate in your own queue before retrying.