Laatst bijgewerkt: 2025-01-22•8 min leestijd

E-mail versturen met Node.js: Complete gids

Leer hoe je transactionele e-mails verstuurt met Node.js via de Truncus SDK. Deze gids behandelt setup, basis verzending, templates en foutafhandeling.

Vereisten

Installatie

Installeer de Truncus Node.js SDK:

npm install @truncus/node

Of met andere package managers:

# Yarn
yarn add @truncus/node

# pnpm
pnpm add @truncus/node

Basis setup

Initialiseer de client met je API key:

import { Truncus } from '@truncus/node';

const truncus = new Truncus({
  apiKey: process.env.TRUNCUS_API_KEY,
});

Je eerste e-mail versturen

Verstuur een simpele HTML e-mail:

const { data, error } = await truncus.emails.send({
  from: 'hallo@jouwdomein.com',
  to: 'gebruiker@voorbeeld.com',
  subject: 'Welkom op ons platform',
  html: '<h1>Welkom!</h1><p>Bedankt voor je aanmelding.</p>',
});

if (error) {
  console.error('Verzenden mislukt:', error.message);
  return;
}

console.log('E-mail verzonden:', data.id);

Naar meerdere ontvangers versturen

Verstuur naar meerdere adressen:

await truncus.emails.send({
  from: 'notificaties@jouwdomein.com',
  to: ['gebruiker1@voorbeeld.com', 'gebruiker2@voorbeeld.com'],
  subject: 'Team update',
  html: '<p>Hier is je wekelijkse samenvatting.</p>',
});

Voeg CC en BCC toe:

await truncus.emails.send({
  from: 'facturatie@jouwdomein.com',
  to: 'klant@voorbeeld.com',
  cc: ['administratie@klant.com'],
  bcc: ['archief@jouwdomein.com'],
  subject: 'Factuur #1234',
  html: factuurHtml,
});

Reply-To gebruiken

Stel een ander antwoordadres in:

await truncus.emails.send({
  from: 'noreply@jouwdomein.com',
  replyTo: 'support@jouwdomein.com',
  to: 'gebruiker@voorbeeld.com',
  subject: 'Je support ticket',
  html: ticketHtml,
});

Plain text fallback

Voeg altijd een plain text versie toe voor toegankelijkheid:

await truncus.emails.send({
  from: 'hallo@jouwdomein.com',
  to: 'gebruiker@voorbeeld.com',
  subject: 'Account verificatie',
  html: '<p>Je code is: <strong>123456</strong></p>',
  text: 'Je code is: 123456',
});

Versturen met bijlagen

Voeg bestanden toe aan je e-mail:

import { readFileSync } from 'fs';

await truncus.emails.send({
  from: 'facturatie@jouwdomein.com',
  to: 'klant@voorbeeld.com',
  subject: 'Je factuur',
  html: '<p>In de bijlage vind je je factuur.</p>',
  attachments: [
    {
      filename: 'factuur.pdf',
      content: readFileSync('./factuur.pdf'),
    },
  ],
});

Custom headers

Voeg aangepaste e-mail headers toe:

await truncus.emails.send({
  from: 'systeem@jouwdomein.com',
  to: 'gebruiker@voorbeeld.com',
  subject: 'Wachtwoord reset',
  html: resetHtml,
  headers: {
    'X-Entity-Ref-ID': gebruikerId,
    'X-Priority': '1',
  },
});

Foutafhandeling

Handel fouten correct af:

import { Truncus, TruncusError } from '@truncus/node';

const truncus = new Truncus({ apiKey: process.env.TRUNCUS_API_KEY });

try {
  const { data, error } = await truncus.emails.send({
    from: 'hallo@jouwdomein.com',
    to: 'gebruiker@voorbeeld.com',
    subject: 'Test',
    html: '<p>Hallo</p>',
  });

  if (error) {
    // API gaf een fout terug
    switch (error.code) {
      case 'rate_limited':
        // Wacht en probeer opnieuw
        await sleep(error.retryAfter * 1000);
        break;
      case 'invalid_recipient':
        // Ongeldig e-mailadres afhandelen
        break;
      case 'domain_not_verified':
        // Domein moet geverifieerd worden
        break;
      default:
        console.error('Verzenden mislukt:', error.message);
    }
    return;
  }

  console.log('Verzonden:', data.id);
} catch (err) {
  // Netwerk of onverwachte fout
  console.error('Onverwachte fout:', err);
}

TypeScript ondersteuning

De SDK is volledig getypeerd. Importeer types waar nodig:

import { Truncus, SendEmailRequest, SendEmailResponse, TruncusError } from '@truncus/node';

const emailRequest: SendEmailRequest = {
  from: 'hallo@jouwdomein.com',
  to: 'gebruiker@voorbeeld.com',
  subject: 'Getypeerde e-mail',
  html: '<p>Dit is type-veilig</p>',
};

const { data, error } = await truncus.emails.send(emailRequest);

Omgevingsconfiguratie

Aanbevolen omgevings-setup:

# .env
TRUNCUS_API_KEY=tr_live_xxxx

# Voor development
TRUNCUS_API_KEY=tr_test_xxxx

Laden met dotenv of je framework's env handling:

import 'dotenv/config';
import { Truncus } from '@truncus/node';

const truncus = new Truncus({
  apiKey: process.env.TRUNCUS_API_KEY!,
});

Framework voorbeelden

Express.js

import express from 'express';
import { Truncus } from '@truncus/node';

const app = express();
const truncus = new Truncus({ apiKey: process.env.TRUNCUS_API_KEY! });

app.post('/verstuur-welkom', async (req, res) => {
  const { email, naam } = req.body;

  const { data, error } = await truncus.emails.send({
    from: 'welkom@jouwdomein.com',
    to: email,
    subject: `Welkom, ${naam}!`,
    html: `<h1>Hallo ${naam}</h1>`,
  });

  if (error) {
    return res.status(400).json({ error: error.message });
  }

  res.json({ messageId: data.id });
});

Next.js API Route

// app/api/contact/route.ts
import { NextResponse } from 'next/server';
import { Truncus } from '@truncus/node';

const truncus = new Truncus({ apiKey: process.env.TRUNCUS_API_KEY! });

export async function POST(request: Request) {
  const { email, bericht } = await request.json();

  const { error } = await truncus.emails.send({
    from: 'contact@jouwdomein.com',
    to: 'team@jouwdomein.com',
    replyTo: email,
    subject: 'Nieuwe contactformulier inzending',
    text: bericht,
  });

  if (error) {
    return NextResponse.json({ error: error.message }, { status: 400 });
  }

  return NextResponse.json({ success: true });
}

Volgende stappen

E-mail versturen met Node.js: Complete gids