Zuletzt aktualisiert: 2025-01-22•8 Min. Lesezeit

E-Mail senden mit Node.js: Vollständiger Leitfaden

Lernen Sie, wie Sie transaktionale E-Mails mit Node.js über das Truncus SDK versenden. Dieser Leitfaden behandelt Setup, grundlegenden Versand, Templates und Fehlerbehandlung.

Voraussetzungen

Installation

Installieren Sie das Truncus Node.js SDK:

npm install @truncus/node

Oder mit anderen Paketmanagern:

# Yarn
yarn add @truncus/node

# pnpm
pnpm add @truncus/node

Grundlegendes Setup

Initialisieren Sie den Client mit Ihrem API-Key:

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

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

Ihre erste E-Mail senden

Senden Sie eine einfache HTML-E-Mail:

const { data, error } = await truncus.emails.send({
  from: 'hallo@ihredomain.com',
  to: 'nutzer@beispiel.com',
  subject: 'Willkommen auf unserer Plattform',
  html: '<h1>Willkommen!</h1><p>Danke für Ihre Anmeldung.</p>',
});

if (error) {
  console.error('Senden fehlgeschlagen:', error.message);
  return;
}

console.log('E-Mail gesendet:', data.id);

An mehrere Empfänger senden

An mehrere Adressen senden:

await truncus.emails.send({
  from: 'benachrichtigungen@ihredomain.com',
  to: ['nutzer1@beispiel.com', 'nutzer2@beispiel.com'],
  subject: 'Team-Update',
  html: '<p>Hier ist Ihre wöchentliche Zusammenfassung.</p>',
});

CC und BCC hinzufügen:

await truncus.emails.send({
  from: 'buchhaltung@ihredomain.com',
  to: 'kunde@beispiel.com',
  cc: ['rechnungswesen@kunde.com'],
  bcc: ['archiv@ihredomain.com'],
  subject: 'Rechnung #1234',
  html: rechnungHtml,
});

Reply-To verwenden

Eine andere Antwortadresse setzen:

await truncus.emails.send({
  from: 'noreply@ihredomain.com',
  replyTo: 'support@ihredomain.com',
  to: 'nutzer@beispiel.com',
  subject: 'Ihr Support-Ticket',
  html: ticketHtml,
});

Klartext-Fallback

Fügen Sie immer eine Klartext-Version für Barrierefreiheit hinzu:

await truncus.emails.send({
  from: 'hallo@ihredomain.com',
  to: 'nutzer@beispiel.com',
  subject: 'Kontoverifizierung',
  html: '<p>Ihr Code lautet: <strong>123456</strong></p>',
  text: 'Ihr Code lautet: 123456',
});

Mit Anhängen senden

Dateien an Ihre E-Mail anhängen:

import { readFileSync } from 'fs';

await truncus.emails.send({
  from: 'buchhaltung@ihredomain.com',
  to: 'kunde@beispiel.com',
  subject: 'Ihre Rechnung',
  html: '<p>Anbei finden Sie Ihre Rechnung.</p>',
  attachments: [
    {
      filename: 'rechnung.pdf',
      content: readFileSync('./rechnung.pdf'),
    },
  ],
});

Benutzerdefinierte Header

Benutzerdefinierte E-Mail-Header hinzufügen:

await truncus.emails.send({
  from: 'system@ihredomain.com',
  to: 'nutzer@beispiel.com',
  subject: 'Passwort zurücksetzen',
  html: resetHtml,
  headers: {
    'X-Entity-Ref-ID': nutzerId,
    'X-Priority': '1',
  },
});

Fehlerbehandlung

Fehler richtig behandeln:

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@ihredomain.com',
    to: 'nutzer@beispiel.com',
    subject: 'Test',
    html: '<p>Hallo</p>',
  });

  if (error) {
    // API hat einen Fehler zurückgegeben
    switch (error.code) {
      case 'rate_limited':
        // Warten und erneut versuchen
        await sleep(error.retryAfter * 1000);
        break;
      case 'invalid_recipient':
        // Ungültige E-Mail-Adresse behandeln
        break;
      case 'domain_not_verified':
        // Domain muss verifiziert werden
        break;
      default:
        console.error('Senden fehlgeschlagen:', error.message);
    }
    return;
  }

  console.log('Gesendet:', data.id);
} catch (err) {
  // Netzwerk- oder unerwarteter Fehler
  console.error('Unerwarteter Fehler:', err);
}

TypeScript-Unterstützung

Das SDK ist vollständig typisiert. Importieren Sie Typen nach Bedarf:

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

const emailRequest: SendEmailRequest = {
  from: 'hallo@ihredomain.com',
  to: 'nutzer@beispiel.com',
  subject: 'Typisierte E-Mail',
  html: '<p>Das ist typsicher</p>',
};

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

Umgebungskonfiguration

Empfohlenes Umgebungs-Setup:

# .env
TRUNCUS_API_KEY=tr_live_xxxx

# Für Entwicklung
TRUNCUS_API_KEY=tr_test_xxxx

Mit dotenv oder dem Env-Handling Ihres Frameworks laden:

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

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

Framework-Beispiele

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('/willkommen-senden', async (req, res) => {
  const { email, name } = req.body;

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

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

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

Next.js API Route

// app/api/kontakt/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, nachricht } = await request.json();

  const { error } = await truncus.emails.send({
    from: 'kontakt@ihredomain.com',
    to: 'team@ihredomain.com',
    replyTo: email,
    subject: 'Neue Kontaktformular-Anfrage',
    text: nachricht,
  });

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

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

Nächste Schritte

E-Mail senden mit Node.js: Vollständiger Leitfaden