⚡
MailPort v0.0.1
npm v0.0.1
✨ Modern Node.js 22+ Email Architecture

Type-Safe, Zero-Copy
Streaming Email SDK

MailPort is a developer-friendly Node.js email gateway built for performance. Streaming MIME generation, robust SMTP delivery, zero third-party core dependencies, and built-in testing utilities.

$ npm install mailport
Get Started →
quickstart.ts 
import { createMailer, smtp } from 'mailport';

const mailer = createMailer({
  transport: smtp({
    host: 'smtp.example.com',
    port: 587,
    tls: 'starttls',
    auth: {
      user: process.env.SMTP_USER!,
      pass: process.env.SMTP_PASS!,
    },
  }),
});

const result = await mailer.send({
  from: 'hello@example.com',
  to: 'user@example.com',
  subject: 'Hello from MailPort 🚀',
  text: 'MailPort is fast, type-safe, and streaming.',
});

console.log('Status:', result.status);

Built for Modern Node.js Developers

Engineered from the ground up for safety, speed, and clean ergonomics.

🛡️

TypeScript-First Engine

Strict type definitions for message options, envelope validation, transport contracts, and typed error hierarchies.

⚡

Zero-Copy Streaming MIME

Emits RFC-compliant MIME streams directly from AsyncIterable sources with constant ~10 MB heap memory usage on 100 MB attachments.

🔒

Strict Security Defaults

Strict TLS certificate and hostname validation enabled by default with support for required STARTTLS and implicit TLS.

🧪

Network-Free Test Suite

Includes `@mailport/testing` with `InMemoryTransport` and inspectable `InMemoryInbox` to test email sending without network mocks.

📦

Zero Core Dependencies

`@mailport/core` has exactly zero third-party runtime dependencies, minimizing supply chain vulnerabilities.

🔍

Phase-Aware Errors

Accurately classifies delivery failures into `not-sent`, `uncertain`, and `sent` states to avoid duplicate message sends.

Interactive Demo

Live MailPort Stream & Transport Simulator

Simulate constructing a message and streaming dot-stuffed MIME payloads live in your browser.

Sender & Message Parameters

Streaming MIME Output & SMTP Protocol Log Ready
// Click "Run Mailer.send() & Stream" to execute...
Guides & Reference

Complete Documentation

Package Installation

You can install the unified umbrella package or individual modular packages depending on your project needs.

Option A: Unified Package (Recommended for most apps)

npm install mailport

Option B: Modular Packages (For minimal bundle sizes)

npm install @mailport/core @mailport/smtp @mailport/testing

Quick Start Guide

Construct a Mailer instance using `smtp()` transport and send a message:

import { createMailer, smtp } from 'mailport';

const mailer = createMailer({
  transport: smtp({
    host: 'smtp.example.com',
    port: 587,
    tls: 'starttls',
    auth: {
      user: process.env.SMTP_USER!,
      pass: process.env.SMTP_PASS!,
    },
  }),
});

const result = await mailer.send({
  from: 'noreply@yourdomain.com',
  to: 'user@example.com',
  subject: 'Order Confirmation #10293',
  text: 'Thank you for your order!',
  html: '<h1>Thank you for your order!</h1><p>Your items are being prepared.</p>',
});

console.log('Result ID:', result.id);
console.log('Accepted recipients:', result.accepted);

SMTP Transport Configuration

`@mailport/smtp` supports STARTTLS, implicit TLS, and SASL PLAIN / LOGIN authentication over secure TLS sockets. 

import { smtp } from '@mailport/smtp';

const transport = smtp({
  host: 'smtp.provider.com',
  port: 465,
  tls: 'implicit', // 'implicit' | 'starttls' | 'none'
  auth: {
    user: 'user@provider.com',
    pass: 'secret-password',
    method: 'plain', // 'plain' | 'login'
  },
  timeoutMs: 30000,
});

Zero-Network Unit & Integration Testing

Use `InMemoryTransport` in Vitest or Jest to inspect sent emails without real network sockets: 

import { describe, expect, it } from 'vitest';
import { InMemoryTransport, createTestMailer } from '@mailport/testing';

describe('User Registration Mailer', () => {
  it('captures welcome email in memory', async () => {
    const transport = new InMemoryTransport();
    const mailer = createTestMailer({ transport });

    await mailer.send({
      from: 'app@example.com',
      to: 'newuser@example.com',
      subject: 'Welcome to App',
      text: 'Thanks for signing up!',
    });

    expect(transport.inbox.count).toBe(1);
    const latest = transport.inbox.latest();
    expect(latest?.to[0].address).toBe('newuser@example.com');
  });
});

Typed Error Hierarchy

MailPort classifies all operational and delivery errors into clear, actionable types:

  • MailError: Base error class with code, category, and retryable flag.
  • MailValidationError: Invalid message options, invalid address format, or missing required fields.
  • MailAuthError: Invalid SMTP username/password credentials (435 / 535 codes).
  • MailConnectionError: Socket connect timeout, network drop, or reset (classified as `deliveryState: 'not-sent'`).
  • MailUncertainError: Network failure after body transmission terminator (`deliveryState: 'uncertain'`).
  • MailCancelledError: Operation aborted via `AbortSignal` (`deliveryState: 'not-sent'`).

API Reference Summary

createMailer(options)

Creates a type-safe Mailer instance wrapping a transport implementation.

smtp(options: SmtpTransportOptions)

Factory function creating an SmtpTransport instance.

InMemoryTransport(options?: InMemoryTransportOptions)

Test transport storing messages in memory.