JSPM

mailstub-client

0.1.0
  • ESM via JSPM
  • ES Module Entrypoint
  • Export Map
  • Keywords
  • License
  • Repository URL
  • TypeScript Types
  • README
  • Created
  • Published
  • Downloads 92
  • Score
    100M100P100Q52632F
  • License MIT

Official client for sending test emails to MailStub

Package Exports

  • mailstub-client
  • mailstub-client/dist/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (mailstub-client) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

mailstub-client

Official client for sending test emails to MailStub.

Installation

npm install mailstub-client

Or using your preferred package manager:

pnpm add mailstub-client
yarn add mailstub-client

Quick Start

Prerequisites

  1. Install and start the MailStub server:

    npm install -g mailstub
# or: pnpm add -g mailstub
# or: yarn global add mailstub

mailstub start

  2. Open http://localhost:8000 and:

    • Create a project
    • Add a test user with an email address
    • Copy your project ID (format: p_xxxxx)

Send Your First Email

import { client } from 'mailstub-client';

await client.send('p_your-project-id', {
  sender: 'noreply@myapp.com',
  receiver: 'user@example.com',
  subject: 'Welcome!',
  body: '<h1>Hello!</h1><p>Thanks for signing up.</p>'
});

API Reference

client.send(projectId, options)

Parameters:

  • projectId (string) - Your project ID (format: p_xxxxx)
  • options (object):
    • sender (string) - Sender email address
    • receiver (string) - Recipient email (must be a user in your project)
    • subject (string) - Email subject line
    • body (string) - Email body (HTML supported)

Returns: Promise with the created message object

Example:

const result = await client.send('p_abc123', {
  sender: 'support@myapp.com',
  receiver: 'testuser@example.com',
  subject: 'Password Reset',
  body: '<p>Click here to reset your password...</p>'
});

console.log('Message ID:', result.message.id);

Custom Port

If your MailStub server runs on a different port:

import { createClient } from 'mailstub-client';

const client = createClient({ port: 3000 });

Usage Examples

Development vs Production

Create an abstraction to switch between MailStub (dev) and real email services (production):

import { client as mailstubClient } from 'mailstub-client';
import sendgrid from '@sendgrid/mail';

sendgrid.setApiKey(process.env.SENDGRID_API_KEY || '');

export async function sendEmail({ to, from, subject, html }) {
  if (process.env.NODE_ENV === 'production') {
    await sendgrid.send({ to, from, subject, html });
  } else {
    await mailstubClient.send(process.env.MAILSTUB_PROJECT_ID!, {
      sender: from,
      receiver: to,
      subject,
      body: html
    });
  }
}

// Usage anywhere in your app:
await sendEmail({
  to: 'user@example.com',
  from: 'noreply@myapp.com',
  subject: 'Welcome!',
  html: '<h1>Welcome!</h1>'
});

Testing Integration

import { client } from 'mailstub-client';
import { describe, it, expect } from 'vitest';

describe('Email notifications', () => {
  it('should send welcome email', async () => {
    const result = await client.send('p_test123', {
      sender: 'test@myapp.com',
      receiver: 'testuser@example.com',
      subject: 'Welcome!',
      body: '<p>Test email</p>'
    });
    
    expect(result.message.id).toMatch(/^m_/);
  });
});

Troubleshooting

"Cannot connect to MailStub server"
Make sure the server is running: mailstub start

"Failed to send email"
Check that:

  • Project ID starts with p_
  • Receiver exists as a user in your project
  • Server is running on the correct port

Custom port not working
Create a client with the custom port and ensure the server started with the same port:

mailstub start --port 3000
const client = createClient({ port: 3000 });

License

MIT