@contract-kit/provider-mail-resend

Resend mail provider for contract-kit that extends your application ports with email sending capabilities using Resend.

Installation

npm install @contract-kit/provider-mail-resend resend
# or
bun add @contract-kit/provider-mail-resend resend

TypeScript Requirements

This package requires TypeScript 5.0 or higher for proper type inference.

Usage

Basic Setup

import { createServer } from "@contract-kit/server";
import { mailResendProvider } from "@contract-kit/provider-mail-resend";

// Set environment variables:
// RESEND_API_KEY=re_...
// RESEND_FROM="My App <[email protected]>"

const app = createServer({
  ports: basePorts,
  providers: [mailResendProvider],
  createContext: ({ ports }) => ({
    ports,
    // ... other context
  }),
  routes: [
    // ... your routes
  ],
});

Sending Emails in Use Cases

Once the provider is registered, your ports will include a mailer property:

// Send plain text email
async function sendWelcomeEmail(ctx: AppCtx, user: User) {
  await ctx.ports.mailer.sendText(
    user.email,
    "Welcome!",
    "Thank you for signing up!"
  );
}

// Send HTML email
async function sendPasswordReset(ctx: AppCtx, user: User, resetLink: string) {
  await ctx.ports.mailer.sendHtml(
    user.email,
    "Password Reset",
    `<h1>Reset Your Password</h1>
     <p>Click <a href="${resetLink}">here</a> to reset your password.</p>`
  );
}

// Send with full options
async function sendCustomEmail(ctx: AppCtx) {
  await ctx.ports.mailer.send({
    from: "[email protected]", // Override default sender
    to: "[email protected]",
    subject: "Custom Email",
    html: "<h1>Hello!</h1>",
  });
}

Configuration

The Resend provider reads configuration from environment variables with the RESEND_ prefix:

| Variable | Required | Description | Example | |----------|----------|-------------|---------| | RESEND_API_KEY | Yes | Resend API key | re_abc123... | | RESEND_FROM | Yes | Default sender email address (must be from verified domain) | "My App <[email protected]>" |

Getting an API Key:

1. Sign up at resend.com
2. Verify your domain
3. Create an API key at resend.com/api-keys

Mailer Port API

The provider extends your ports with the following mailer interface:

sendText(to: string, subject: string, text: string): Promise<void>

Send a plain text email using the default sender address.

await ctx.ports.mailer.sendText(
  "[email protected]",
  "Welcome",
  "Thanks for joining!"
);

sendHtml(to: string, subject: string, html: string): Promise<void>

Send an HTML email using the default sender address.

await ctx.ports.mailer.sendHtml(
  "[email protected]",
  "Welcome",
  "<h1>Thanks for joining!</h1>"
);

send(options: SendTextOptions | SendHtmlOptions): Promise<void>

Send an email with full control over options, including the ability to override the sender.

await ctx.ports.mailer.send({
  from: "[email protected]", // Optional sender override
  to: "[email protected]",
  subject: "Hello",
  html: "<p>Custom email</p>",
});

client: Resend

Access the underlying Resend client for advanced operations.

// Use Resend features directly
const { data, error } = await ctx.ports.mailer.client.emails.send({
  from: "[email protected]",
  to: ["[email protected]", "[email protected]"],
  subject: "Bulk Email",
  html: "<p>Message to multiple recipients</p>",
  tags: [
    { name: "category", value: "newsletter" },
  ],
  attachments: [
    {
      filename: "document.pdf",
      content: pdfBuffer,
    },
  ],
});

TypeScript Support

To get proper type inference for the mailer port, extend your ports type:

import type { MailerPort } from "@contract-kit/mail";
import type { Resend } from "resend";

// Your base ports
const basePorts = definePorts({
  db: dbAdapter,
});

// After using mailResendProvider, your ports will have this shape:
type AppPorts = typeof basePorts & {
  mailer: MailerPort<Resend>;
};

Lifecycle

The Resend Mail provider:

1. During register:
   • Creates Resend client with API key
   • Adds the mailer port
2. During onAppStop: No cleanup needed (Resend client is stateless)

Error Handling

The provider will throw errors in these cases:

• Missing required environment variables
• Invalid API key
• Invalid email addresses
• Domain not verified in Resend

Make sure to handle these during application startup.

Comparing with SMTP Provider

Resend offers several advantages over traditional SMTP:

• Simpler setup: Just an API key, no SMTP server configuration
• Better deliverability: Resend handles infrastructure and reputation
• Modern features: Built-in analytics, webhooks, and templates
• No port/firewall issues: Uses HTTPS instead of SMTP ports

Use the SMTP provider (@contract-kit/provider-mail-smtp) if you need to:

• Use your existing SMTP server
• Have strict data residency requirements
• Integrate with legacy email systems

License

MIT