Mailsurge Node.js SDK

Official Node.js client for the Mailsurge transactional email API.

Requirements

• Node.js 18+ (native fetch)

Installation

npm install @mailsurge/node

Usage

Set your API key in the environment:

MAILSURGE_API_KEY=sk_yourkey

Send a message:

import Mailsurge from '@mailsurge/node';

const mailsurge = new Mailsurge();

await mailsurge.messages.send({
  from: 'Acme <[email protected]>',
  to: ['[email protected]'],
  subject: 'Welcome to Acme',
  html: '<p>Your account is ready.</p>',
  text: 'Your account is ready.',
});

Pass the key explicitly when you prefer not to use environment variables:

const mailsurge = new Mailsurge({ apiKey: process.env.MAILSURGE_API_KEY });

Attachments and headers

await mailsurge.messages.send({
  from: 'Sender <[email protected]>',
  to: '[email protected]',
  subject: 'Hello',
  html: '<p>See attached.</p>',
  headers: {
    'X-Campaign': 'welcome',
  },
  attachments: [
    {
      filename: 'hello.txt',
      content: Buffer.from('Hello world!').toString('base64'),
      content_type: 'text/plain',
      disposition: 'attachment',
    },
  ],
});

Error handling

Non-2xx responses raise typed errors:

import {
  MailsurgeAuthenticationError,
  MailsurgeRateLimitError,
  MailsurgeValidationError,
} from '@mailsurge/node';

try {
  await mailsurge.messages.send({ /* ... */ });
} catch (error) {
  if (error instanceof MailsurgeRateLimitError) {
    console.error('Limit:', error.body.limit);
  }
}

Configuration

| Variable | Description | | --- | --- | | MAILSURGE_API_KEY | API key from the Mailsurge dashboard | | MAILSURGE_API_URL | Optional API base URL (defaults to https://mailsurge.dev) |

Testing

npm test

License

MIT. See LICENSE.