@unireq/smtp

SMTP transport with a pluggable connector architecture. Ships with a default connector powered by nodemailer, but you can bring your own implementation (BYOC).

Installation

pnpm add @unireq/smtp

# For the default connector (optional peer dependency)
pnpm add nodemailer

Quick Start

import { client } from '@unireq/core';
import { smtp } from '@unireq/smtp';

const { transport } = smtp('smtp://user:[email protected]:587');
const mail = client(transport);

const result = await mail.post('/', {
  from: '[email protected]',
  to: '[email protected]',
  subject: 'Hello!',
  text: 'This is a test email.',
});

Features

| Category | Symbols | Purpose | | --- | --- | --- | | Transport | smtp(uri?, connector?) | SMTP/SMTPS transport factory | | Default connector | NodemailerConnector | Implementation using nodemailer | | Types | EmailMessage, EmailAttachment, SendResult | Email composition structures |

Email Message Format

const message = {
  from: '[email protected]',
  to: '[email protected]',
  subject: 'Email Subject',
  text: 'Plain text body',
  html: '<h1>HTML body</h1>',
  cc: '[email protected]',
  bcc: ['[email protected]'],
  attachments: [
    { filename: 'doc.pdf', content: buffer, contentType: 'application/pdf' },
  ],
};

Gmail Authentication

App Password (Development)

const { transport } = smtp('smtp://[email protected]:[email protected]:587');

OAuth2 (Production)

const { transport } = smtp('smtp://[email protected]@smtp.gmail.com:587', {
  oauth2: {
    clientId: 'your-client-id.apps.googleusercontent.com',
    clientSecret: 'your-client-secret',
    refreshToken: 'your-refresh-token',
  },
});

Bring Your Own Connector

import type { SMTPConnector, SMTPSession } from '@unireq/smtp';

class MySMTPConnector implements SMTPConnector {
  readonly capabilities = { smtp: true, smtps: true, starttls: true, oauth2: false, html: true, attachments: true };

  async connect(uri: string): Promise<SMTPSession> { /* ... */ }
  async request(session, context) { /* ... */ }
  disconnect(session) { /* ... */ }
}

const { transport } = smtp('smtp://server.com', new MySMTPConnector());

Documentation

Full documentation available at unireq.dev

License

MIT