SDP Email for Next.js

Send email through the SDP Email API from Next.js server components, route handlers, and server actions — or any Node.js 18+ app.

Zero dependencies. TypeScript-first. ESM and CommonJS.

Server-side only. Your API key must never be shipped to the browser. Use this package in server components, route handlers, server actions, or API routes — never in client components.

Installation

npm install sdp-email-nextjs

Setup

Create an API key with the sending scope in your SDP Email dashboard, then add it to .env.local:

SDP_EMAIL_KEY=sdp_xxxxxxxxxxxxxxxxxxxx

Usage

import { SdpEmail } from 'sdp-email-nextjs';

const sdp = new SdpEmail(); // reads SDP_EMAIL_KEY from the environment

const { data, error } = await sdp.emails.send({
    from: 'Acme <[email protected]>',
    to: '[email protected]',
    subject: 'Welcome!',
    html: '<p>Thanks for signing up.</p>',
});

if (error) {
    console.error(error.name, error.message);
} else {
    console.log('Sent:', data.id);
}

In a server action

'use server';

import { SdpEmail } from 'sdp-email-nextjs';

const sdp = new SdpEmail();

export async function sendContactMessage(formData: FormData) {
    const { error } = await sdp.emails.send({
        from: 'Website <[email protected]>',
        to: '[email protected]',
        reply_to: String(formData.get('email')),
        subject: 'New contact message',
        text: String(formData.get('message')),
    });

    return { ok: !error };
}

In a route handler

// app/api/send/route.ts
import { NextResponse } from 'next/server';
import { SdpEmail } from 'sdp-email-nextjs';

const sdp = new SdpEmail();

export async function POST(request: Request) {
    const body = await request.json();

    const { data, error } = await sdp.emails.send({
        from: 'Acme <[email protected]>',
        to: body.to,
        subject: body.subject,
        html: body.html,
    });

    if (error) {
        return NextResponse.json(error, { status: error.statusCode || 500 });
    }

    return NextResponse.json(data);
}

Retrieve a sent email

const { data } = await sdp.emails.get('a3f1c9e2-...');
// { object: 'email', id, from, to, subject, html, text, created_at, last_event }

Send options

| Field | Type | Notes | | --- | --- | --- | | from | string | Required. "Name <user@domain>" — the domain must be verified for your API key. | | to | string \| string[] | Required. | | subject | string | Optional. | | html | string | Required unless text is set. | | text | string | Required unless html is set. | | cc, bcc | string \| string[] | Optional. | | reply_to / replyTo | string \| string[] | Optional. | | headers | Record<string, string> | Optional. Reserved headers (From, To, Subject, ...) are ignored. | | attachments | { filename, content, content_type? }[] | content is base64-encoded. |

Error handling

Methods never throw on API errors. They return { data, error }:

const { data, error } = await sdp.emails.send(payload);

if (error) {
    // { statusCode: 401, message: 'Invalid API key', name: 'invalid_api_key' }
}

Network failures and timeouts are returned as an error with statusCode: 0 and name: 'application_error'.

Configuration

const sdp = new SdpEmail('sdp_...', {
    baseUrl: 'https://email.sdp-platform.com', // or SDP_EMAIL_ENDPOINT env var
    timeout: 10_000, // milliseconds
});

| Env variable | Purpose | | --- | --- | | SDP_EMAIL_KEY (or SDP_EMAIL_API_KEY) | API key used when none is passed to the constructor. | | SDP_EMAIL_ENDPOINT | Override the API base URL. |

License

MIT