Skip to main content

Next.js

Use the JavaScript SDK in a Next.js App Router application running Node.js 22 or later. Keep sending in server-side code.

Before you start​

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

Install and configure​

npm install @epostix/sdk server-only
.env.local
EPOSTIX_API_KEY=your_api_key

Keep this file out of Git. Do not use a NEXT_PUBLIC_ prefix: it would expose the key in the browser bundle.

Create a server-only send function​

lib/email.ts
import 'server-only';
import { Epostix } from '@epostix/sdk';

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

const client = new Epostix({ apiKey });

export async function sendWelcome(userId: string, emailAddress: string) {
  return client.emails.sendEmail({
    from: 'hello@mail.yourdomain.com',
    to: [emailAddress],
    subject: 'Welcome',
    html: '<p>Your account is ready.</p>',
    text: 'Your account is ready.',
  }, {
    idempotencyKey: `user-${userId}-welcome`,
  });
}

Replace the sender with your verified address. Call sendWelcome from your existing account-creation code after the user has been saved. Pass the saved user's ID and email address. Await the call or run it in a durable background job, so a failed send is recorded and can be retried.

The module is server-only, and is not itself a public endpoint. If a Route Handler or Server Action calls it, authenticate and validate that operation before sending. Use the Node.js runtime for this example.

Handle the result​

The promise resolves to the accepted email, including id. It rejects on failure. API errors are EpostixApiError instances with type, status and requestId; transport failures can have other error types. See the Node.js example for error handling.

A successful call confirms acceptance. Use Activity or webhooks for delivery status.

Keep retries tied to one event​

user-${userId}-welcome stays the same when the account-creation job retries. Keep the body and API key unchanged too. Deduplication lasts 24 hours; it is not a permanent record that a user has received a welcome email.

For recurring messages, include the specific event or occurrence in the key. See idempotency.

Contact forms​

Send from your own verified domain and put the visitor's address in the SDK's replyTo field (reply_to over HTTP). Validate the address and message, limit submissions, and keep the destination under your control. An endpoint that accepts arbitrary recipients can be used to send unwanted mail.

Next​