Mailtrap

Send through the Mailtrap Email Sending API with full field support and provider-side message inspection.

Capabilities

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

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

The Mailtrap adapter calls the Mailtrap Email Sending API with plain fetch. It supports every common transactional field, and Mailtrap's inspection tooling makes it a natural pick for staging environments.

Mailtrap@opencoredev/email-sdk/mailtrap

Provider docs

Configure

Create a Mailtrap API token with Email Sending permission and verify your sending domain.

lib/email.ts

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

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

Prop

Type

Send

Mailtrap maps cc, bcc, headers, attachments, metadata, and tags, with two limits: at most one tag (its value becomes the Mailtrap category) and at most one replyTo. metadata is sent as custom_variables with values stringified (null becomes "").

const result = await email.send({
  from: "Acme <hello@acme.com>",
  to: "user@example.com",
  cc: "billing@acme.com",
  replyTo: "support@acme.com",
  subject: "Your receipt for order ord_123",
  html: "<p>Thanks for your order. Receipt attached.</p>",
  tags: [{ name: "type", value: "receipt" }],
  metadata: { orderId: "ord_123" },
  attachments: [
    { filename: "receipt.pdf", path: "./receipts/ord_123.pdf" },
  ],
});

console.log(result.id); // first entry of Mailtrap's message_ids

One tag, one reply-to

A second tag or a second replyTo throws an EmailValidationError before any request. Trim to one of each when Mailtrap sits in a fallback route behind a multi-tag adapter.

Verify from the CLI

MAILTRAP_API_KEY="..." npx --package @opencoredev/email-sdk email-sdk doctor --adapter mailtrap

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

Drop --dry-run for one real smoke send, and confirm the token targets the intended Mailtrap project before pointing production at it.

Frequently asked questions

Does Email SDK support Mailtrap?

Yes. Email SDK ships a Mailtrap adapter imported from @opencoredev/email-sdk/mailtrap. You keep your Mailtrap 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 Mailtrap adapter support?

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

Can Mailtrap schedule email for later with Email SDK?

No. Mailtrap has no provider-side scheduling, so a message with sendAt fails validation. Store the job in your own queue and send when it is due.

Does the Mailtrap adapter support idempotent sends?

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