@contract-kit/provider-mail-smtp

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

Installation

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

TypeScript Requirements

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

Usage

Basic Setup

import { createServer } from "@contract-kit/server";
import { mailSmtpProvider } from "@contract-kit/provider-mail-smtp";

// Set environment variables:
// MAIL_HOST=smtp.example.com
// MAIL_PORT=587
// [email protected]
// MAIL_PASS=password123
// [email protected]

const app = createServer({
  ports: basePorts,
  providers: [mailSmtpProvider],
  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 Mail provider reads configuration from environment variables with the MAIL_ prefix:

| Variable | Required | Description | Example | |----------|----------|-------------|---------| | MAIL_HOST | Yes | SMTP server hostname | smtp.gmail.com | | MAIL_PORT | Yes | SMTP server port | 587 (TLS) or 465 (SSL) | | MAIL_USER | Yes | SMTP username | [email protected] | | MAIL_PASS | Yes | SMTP password | your-password | | MAIL_FROM | Yes | Default sender email address | [email protected] |

Note: Port 465 automatically uses SSL, while other ports use TLS.

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: Transporter

Access the underlying nodemailer transporter for advanced operations.

// Use nodemailer features directly
await ctx.ports.mailer.client.sendMail({
  from: "[email protected]",
  to: ["[email protected]", "[email protected]"],
  subject: "Bulk Email",
  text: "Message to multiple recipients",
  attachments: [
    {
      filename: "document.pdf",
      path: "/path/to/document.pdf",
    },
  ],
});

TypeScript Support

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

import type { MailerPort } from "@contract-kit/mail";
import type { Transporter } from "nodemailer";

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

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

Popular SMTP Providers

Gmail

MAIL_HOST=smtp.gmail.com
MAIL_PORT=587
[email protected]
MAIL_PASS=your-app-password  # Use App Password, not regular password
[email protected]

SendGrid

MAIL_HOST=smtp.sendgrid.net
MAIL_PORT=587
MAIL_USER=apikey
MAIL_PASS=your-sendgrid-api-key
[email protected]

AWS SES

MAIL_HOST=email-smtp.us-east-1.amazonaws.com
MAIL_PORT=587
MAIL_USER=your-ses-smtp-username
MAIL_PASS=your-ses-smtp-password
[email protected]

Lifecycle

The SMTP Mail provider:

1. During register:
   • Creates nodemailer transporter
   • Verifies connection to SMTP server
   • Adds the mailer port
2. During onAppStop: Closes the transporter connection

Error Handling

The provider will throw errors in these cases:

• Missing required environment variables
• Failed connection to SMTP server
• Invalid email addresses

Make sure to handle these during application startup.

License

MIT