[01 / ARCHITECTURE] ZERO-COPY STREAMING ENGINE

STREAMING EMAIL SDK FOR NODE.JS

MailPort is a developer-focused Node.js 22+ email library. Engineered for zero-copy MIME generation, single-connection SMTP transport with mandatory TLS and SASL authentication, and zero-network in-memory test suites.

$ npm install mailport
LAUNCH PLAYGROUND → DOCUMENTATION
0 CORE DEPENDENCIES
100% TYPESCRIPT STRICT
STREAM ZERO BUFFER SPIKE
examples/send-transactional.ts TYPESCRIPT 
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: 'App System <noreply@example.com>',
  to: 'user@domain.com',
  subject: 'Transactional Verification',
  text: 'Your authentication code is 849204.',
  html: '<h1>Verification</h1><p>Code: <strong>849204</strong></p>',
});

console.log('[MailPort Result]', result.status, result.accepted);
[02 / INSTALLATION]

GET STARTED IN SECONDS

OPTION 01

UNIFIED UMBRELLA PACKAGE

Recommended for standard applications. Includes core mailer engine, MIME stream builder, SMTP network transport, and in-memory testing utilities.

npm install mailport
OPTION 02

MODULAR PACKAGES

Install lightweight individual modules for strict bundle optimization and decoupling of transport dependencies.

npm install @mailport/core @mailport/smtp npm install --save-dev @mailport/testing
[03 / INTERACTIVE SIMULATOR]

PLAYGROUND & MIME INSPECTOR

MESSAGE COMPOSER

RFC 5322 SPEC 
Execute simulation to generate MIME output.
INMEMORY INBOX 
Execute simulation to view inbox result.
EXECUTABLE CODE 
Generating code snippet...
[04 / MONOREPO ECOSYSTEM]

WORKSPACE PACKAGES

mailport UMBRELLA

Unified entry package re-exporting core engine, MIME streams, SMTP transport, and testing matchers.

npm install mailport
@mailport/core ZERO DEPS

Mailer engine, address parsing, CR/LF injection safety checks, lifecycle hooks, and error hierarchy.

npm install @mailport/core
@mailport/mime MIME STREAM

Zero-copy streaming MIME builder, Base64 chunk encoder, Quoted-Printable encoder, RFC 2231 filename parameters.

npm install @mailport/mime
@mailport/smtp TRANSPORT

Single-connection SMTP transport with mandatory TLS upgrade, SASL PLAIN/LOGIN auth, and dot-stuffing.

npm install @mailport/smtp
@mailport/testing TESTING

Zero-network InMemoryTransport and inspectable InMemoryInbox for fast unit testing.

npm install --save-dev @mailport/testing
[05 / GUIDES]

DOCUMENTATION & CODE SNIPPETS

BASIC EMAIL DELIVERY

import { createMailer, smtp } from 'mailport';

const mailer = createMailer({
  transport: smtp({
    host: 'smtp.mailtrap.io',
    port: 2525,
    auth: {
      user: process.env.SMTP_USER!,
      pass: process.env.SMTP_PASS!,
    },
  }),
});

const result = await mailer.send({
  from: 'Acme Security <security@acme.com>',
  to: 'alice@example.com',
  subject: 'Verification Code',
  text: 'Code: 849204',
  html: '<p>Code: <strong>849204</strong></p>',
});

console.log(result.id, result.accepted);

SMTP SECURITY & TLS

import { SmtpTransport } from '@mailport/smtp';
import { Mailer } from '@mailport/core';

const transport = new SmtpTransport({
  host: 'smtp.sendgrid.net',
  port: 587,
  tls: 'starttls',
  auth: { user: 'apikey', pass: process.env.SENDGRID_API_KEY! },
});

const mailer = new Mailer({ transport });
await transport.validate();

UNIT TESTING FLOW

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

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

    await mailer.send({
      from: 'app@example.com',
      to: 'user@domain.com',
      subject: 'Welcome',
      text: 'Hello',
    });

    expect(transport.inbox.count).toBe(1);
  });
});

STREAMED ATTACHMENTS

import { createReadStream } from 'node:fs';
import { createMailer, smtp } from 'mailport';

const mailer = createMailer({ transport: smtp({ host: 'smtp.example.com' }) });

await mailer.send({
  from: 'billing@example.com',
  to: 'customer@domain.com',
  subject: 'Invoice',
  text: 'Statement attached.',
  attachments: [
    {
      type: 'path',
      filename: 'statement.pdf',
      path: './statement.pdf',
      contentType: 'application/pdf',
    },
  ],
});

LIFECYCLE HOOKS

import { Mailer, SmtpTransport } from 'mailport';

const mailer = new Mailer({
  transport: new SmtpTransport({ host: 'smtp.example.com' }),
  hooks: {
    onBeforeSend(message, context) {
      console.log(`[${context.attemptId}] Sending...`);
    },
    onAfterSend(result, message, context) {
      console.log(`[${context.attemptId}] Delivered in ${result.durationMs}ms`);
    },
  },
});
[06 / SPECIFICATIONS]

API & ERROR HIERARCHY

ERROR CLASSIFICATION TABLE

ERROR CLASS CODE RETRYABLE
MailValidationError ERR_MAIL_VALIDATION NO
MailAuthError ERR_MAIL_AUTH NO
MailConnectionError ERR_MAIL_CONNECTION YES
MailTlsError ERR_MAIL_TLS NO
MailRateLimitError ERR_MAIL_RATE_LIMIT YES

ADDRESS PARSING CONTRACT

import { parseAddress } from '@mailport/core';

// Display Name Format
parseAddress('Alice <alice@domain.com>');
// => { name: 'Alice', address: 'alice@domain.com' }

// Object Representation
parseAddress({ name: 'Bob', address: 'bob@domain.com' });

// Plain Address
parseAddress('user@domain.com');
[07 / BENCHMARKS]

TECHNICAL PERFORMANCE

0 KB BUFFER OVERHEAD

Streams chunks directly to network sockets without memory buffering.

< 0.5 ms STARTUP TIME

Instant header folding and boundary generation initialization.

1 REQ PER SEND MODEL

Clean single-connection lifecycle eliminates stale pool corruption.