Skip to main content

Node.js

Use the official JavaScript SDK from Node.js 22 or later. It includes TypeScript types.

Before you start​

You need a verified sending domain and an API key with the sending scope. Keep the key on the server.

Install​

npm install @epostix/sdk

Set EPOSTIX_API_KEY in your server environment. For a local test, put it in an untracked .env file:

.env
EPOSTIX_API_KEY=your_api_key

Send an email​

Save this as send.mjs. Replace the sender with an address at your verified domain and the recipient with your own address.

send.mjs
import { Epostix, EpostixApiError } from '@epostix/sdk';

const apiKey = process.env.EPOSTIX_API_KEY;
if (!apiKey) throw new Error('Set EPOSTIX_API_KEY');

const client = new Epostix({ apiKey });

try {
  const email = await client.emails.sendEmail({
    from: 'hello@mail.yourdomain.com',
    to: ['you@yourdomain.com'],
    subject: 'Your first email',
    html: '<p>Sent with Epostix.</p>',
    text: 'Sent with Epostix.',
  }, {
    idempotencyKey: 'first-email-001',
  });

  console.log(email.id);
} catch (error) {
  if (error instanceof EpostixApiError) {
    console.error(error.type, error.message, error.requestId);
  } else {
    console.error(error);
  }
  process.exitCode = 1;
}
node --env-file=.env send.mjs

The returned ID means Epostix accepted the message. Open Activity or use webhooks to follow delivery. Acceptance does not confirm inbox placement.

Retry the same send​

Running this example again with the same key and body returns the original response within the 24-hour idempotency window. Change the key for a new message. In an application, use an identifier such as order-4821-receipt and keep it across queue retries.

The SDK handles bounded retries for eligible failures. Daily and monthly quota errors need action from your application; they are not retried automatically.

Test without delivering​

Use a test API key or send to delivered@epostix.dev. The sender still needs to belong to a verified domain. See test mode for simulated bounces and other outcomes.

Next​