Quickstart

Get your first email webhook in 5 minutes.

1. Create an account

Sign up at primitive.dev and add your first domain.

2. Configure DNS

Add the MX record shown in your dashboard to your domain's DNS settings. This tells email servers to route mail through Primitive.

yourdomain.com.  MX  10  mx1.primitive.dev.

DNS propagation typically takes a few minutes to a few hours.

3. Add a webhook endpoint

In your dashboard, add the URL where you want to receive emails. Primitive will POST a JSON payload to this URL for every email received.

4. Handle the webhook

Pick your SDK, install it, and use the raw request body with yourPRIMITIVE_WEBHOOK_SECRETfrom the dashboard.

Next.js App Router handler.

import {
  confirmedHeaders,
  handleWebhook,
  PrimitiveWebhookError,
} from '@primitivedotdev/sdk';

export async function POST(req: Request) {
  const body = await req.text();

  try {
    const event = handleWebhook({
      body,
      headers: req.headers,
      secret: process.env.PRIMITIVE_WEBHOOK_SECRET!,
    });

    console.log('Event:', event.id);
    console.log('Email from:', event.email.headers.from);
    console.log('Subject:', event.email.headers.subject);

    return Response.json(
      { received: true },
      { headers: confirmedHeaders() }
    );
  } catch (error) {
    if (error instanceof PrimitiveWebhookError) {
      return Response.json({ error: error.code }, { status: 400 });
    }

    throw error;
  }
}

handleWebhook already verifies the signature, parses the JSON body, and validates email.received for you.

5. Send a test email

Send an email to any address at your domain. Within seconds, you should receive a webhook at your endpoint.

Ready to dive deeper? Check out the Webhook Payload reference for the full schema, the Signature Verification guide for lower-level verification, and the SDKspage for full language details.