E-Mail über API in JavaScript senden (Node.js Tutorial)

Inhaltsübersicht
Inhaltsübersicht 14 Abschnitte
Erste Schritte
E-Mails senden
Produktion
Referenz
JavaScript-Tutorial

Wie man E-Mail über API senden in JavaScript (Node.js Tutorial)

Überspringe die SMTP-Standardtexte. Diese Anleitung zeigt dir, wie du E-Mails in Node.js mit dem Unipile einheitliche E-Mail-API - mit Copy-Paste-Code für Gmail, Outlook und SMTP in unter 10 Zeilen JavaScript.

E-Mail Senden API JavaScript node.js E-Mail-API Gmail / Outlook / SMTP ESM + async/await
sendEmail.mjs
import { UnipileClient } from 'unipile-node-sdk'; const client = neu UnipileClient( process.env.UNIPILE_DSN, process.env.UNIPILE_TOKEN ); await client.email.senden.({ account_id: 'IHRE_KONTO_ID', an: [{ anzeige_name: 'Alice', kennung: 'alice@example.com' }], Betreff: 'Hallo von Node.js', body: '

Gesendet über Unipile!

'
});
E-Mail zugestellt - 202 Akzeptiert
Kompatibel mit: Google Mail Ausblick IMAP
Zu lang; nicht gelesen

5-Zeilen Node.js Beispiel

Wenn du schon weißt, was ein E-Mail senden API ist und möchte einfach nur E-Mail-API-JavaScript-Code senden, der tatsächlich funktioniert. Hier ist er. Das vollständige Tutorial folgt unten.

1
Installieren Sie das SDK
npm unipile-node-sdk installieren
2
Umgebungsvariablen setzen
Hinzufügen UNIPILE_DSN und UNIPILE_TOKEN zu dir .env Datei.
3
E-Mail-Konto verknüpfen
OAuth für Gmail/Outlook oder SMTP-Zugangsdaten für jeden IMAP-Server – ein API-Aufruf.
4
Rufen client.email.sende()
Pass account_id, zu, Themaund Körper. Erledigt.
derselbe Code funktioniert für Gmail, Outlook und jeden IMAP-Server – keine anbieterspezifische Logik erforderlich. Prüfen Sie die E-Mail-API-Leitfaden Für die vollständige Konzeptübersicht.
senden.mjs
import { UnipileClient } from 'unipile-node-sdk'; const client = neu UnipileClient( process.env.UNIPILE_DSN, process.env.UNIPILE_TOKEN ); const Ergebnis = await client.email.senden.({ account_id: 'acc_xxxxxxxxxxxxxxxx', an: [{ display_name: 'Alice Martin', Kennung: 'alice@acme.com' }], Betreff: 'Hallo von Node.js', body: '

Gesendet über die Unipile API!

'
}); Konsole.log(Ergebnis); // { tracking_id: 'msg_...' }
Einrichtung

Voraussetzungen & Einrichtung

Bevor Sie den JavaScript-Workflow der E-Mail-Sendungs-API in der Produktion verwenden können, benötigen Sie vier Dinge: eine unterstützte Node.js-Version, das Unipile SDK, einen API-Schlüssel und einen DSN-Endpunkt.

Node.js 18+ (20 empfohlen)
Das Unipile SDK verwendet native fetch und auf oberster Ebene await. Node 20 LTS wird für die Produktion empfohlen. Überprüfen Sie Ihre Version mit node -v.
Unipile API-Schlüssel & DSN
Registrieren Sie sich im Unipile Dashboard, um Ihren Zugriffstoken und DSN (einen persönlichen HTTPS-Endpunkt wie api4.unipile.com:13444). Beide sind erforderlich, um den Client zu initialisieren.
ESM oder CommonJS
Das SDK unterstützt beides. Für ESM verwenden Sie .mjs Dateien oder Satz "type":"module" in package.json. Für CommonJS, dynamisch import() funktioniert auch - Beispiele siehe unten.
Ein verknüpftes E-Mail-Konto
Sie senden E-Mail durch ein verknüpftes Konto (Gmail, Outlook oder IMAP). Der nächste Abschnitt führt Sie durch den OAuth-Flow, um eines zu verknüpfen. Dies tun Sie nur einmal pro Konto.
Installation des Unipile SDK
npm
Garn
pnpm
npm unipile-node-sdk installieren
yarn add unipile-node-sdk
pnpm add unipile-node-sdk
.env
# Unipile-Anmeldedaten (diese Datei niemals einchecken) UNIPILE_DSN=https://api4.unipile.com:13444 UNIPILE_TOKEN=dein_zugangstoken_hier # Die Konto-ID des verknüpften E-Mail-Kontos EMAIL_KONTO_ID=acc_xxxxxxxxxxxxxxxx

Hinzufügen .env zu dir .gitignore. Benutzen dotenv oder das native Node 20.6+ --env-datei Flagge zum Laden: node --env-file=.env send.mjs.

Konto verknüpfen

Einrichten Ihres ersten E-Mail-Kontos

Die Vereinheitlichte E-Mail-API ein einzelnes verwendet account_id um Anbieterunterschiede zu abstrahieren. Ein Konto einmal verknüpfen, dann aufrufen client.email.sende() identisch über alle drei Anbieter hinweg.

Wählen Sie unten Ihren Anbieter aus, um den genauen Node.js-Snippet anzuzeigen. Die zurückgegebene account_id ist das, was Sie speichern und für jede nachfolgende Übertragung wiederverwenden.

Google MailGmail OAuth
AusblickOutlook / Microsoft 365
IMAPSMTP / IMAP
connect-gmail.mjs
import { UnipileClient } from 'unipile-node-sdk'; const client = neu UnipileClient(process.env.UNIPILE_DSN, process.env.UNIPILE_TOKEN); // Schritt 1: Erstellen Sie einen gehosteten OAuth-Link für Gmail const { url } = await Kunde.Konto.createHostedAuthLink({ typ: 'GOOGLE', success_redirect_url: process.env.OAUTH_CALLBACK_URL, failure_redirect_url: process.env.OAUTH_CALLBACK_URL + '?error=1', }); // Schritt 2: Umleiten Ihres Benutzers zu `url` Konsole.log('Benutzer weiterleiten zu:', URL); // Schritt 3: Unipile sendet die account_id an Ihren Callback // Speichern Sie es: process.env.EMAIL_ACCOUNT_ID = result.account_id
connect-outlook.mjs
import { UnipileClient } from 'unipile-node-sdk'; const client = neu UnipileClient(process.env.UNIPILE_DSN, process.env.UNIPILE_TOKEN); // Funktioniert für privates Outlook UND Microsoft 365 / Exchange Online const { url } = await Kunde.Konto.createHostedAuthLink({ typ: 'MICROSOFT', success_redirect_url: process.env.OAUTH_CALLBACK_URL, failure_redirect_url: process.env.OAUTH_CALLBACK_URL + '?error=1', }); // Weiterleitung des Benutzers, damit er den Microsoft OAuth-Flow abschließt Konsole.log('Benutzer weiterleiten zu:', URL); // Siehe: /syncing-emails-with-microsoft-graph-api-a-developers-guide/
connect-imap.mjs
import { UnipileClient } from 'unipile-node-sdk'; const client = neu UnipileClient(process.env.UNIPILE_DSN, process.env.UNIPILE_TOKEN); // SMTP/IMAP: Anmeldeinformationen direkt übergeben (keine OAuth-Umleitung) const account = await Kunde.Konto.create({ typ: 'IMAP', imap: { username: process.env.IMAP_BENUTZER, passwort: process.env.IMAP_PASS, host: process.env.IMAP_HOST, Hafen: 993,}, smtp: { username: process.env.IMAP_BENUTZER, passwort: process.env.IMAP_PASS, host: process.env.SMTP_HOST, Hafen: 587, }, }); Konsole.log(account.account_id); // speichen Sie dies
Google Mail Google Mail
Verwendet Google OAuth 2.0. Keine App-Passwörter erforderlich. Sehen Sie die vollständige Gmail API E-Mail senden Tutorial für Scopes und Einrichtungsbildschirme für die Zustimmung.
Ausblick Outlook / Microsoft 365
Verwendet Microsoft Graph OAuth. Behandelt persönliche Outlook- und M365-Tenants. Details in der Microsoft Graph E-Mail-Leitfaden.
IMAP SMTP / IMAP
Funktioniert mit jedem Anbieter, der IMAP/SMTP (Yahoo, ProtonMail Bridge, benutzerdefinierte Mailserver) unterstützt. Lesen Sie die IMAP API-Lösungsleitfaden.
Kern-API

Ihre erste E-Mail von Node.js senden

Drei produktionsreife Muster für den JavaScript-Workflow der E-Mail-Send-API: Nur-Text, HTML mit CC/BCC und Lesen des Antwortobjekts. Alle verwenden die gleiche client.email.sende() rufen.

1
Nur-Text-E-Mail
Einfachster Fall
Flachtext.mjs
import { UnipileClient } from 'unipile-node-sdk'; const client = neu UnipileClient(process.env.UNIPILE_DSN, process.env.UNIPILE_TOKEN); const Ergebnis = await client.email.senden.({ account_id: process.env.EMAIL_KONTO_ID, an: [{ anzeige_name: 'Bob', Kennung: 'bob@example.com' }], Betreff: 'Willkommen auf der Plattform', body: 'Hallo Bob, dein Konto ist bereit.', }); Konsole.log(result.tracking_id); // msg_xxxxxxxxxxxxxxxx
202 Akzeptiert - result.tracking_id ausgefüllt
2
HTML-Body mit CC und BCC
Mehrere Empfänger
html-cc-bcc.mjs
const Ergebnis = await client.email.senden.({ account_id: process.env.EMAIL_KONTO_ID, an: [{ display_name: 'Alice', Kennung: 'alice@acme.com' }], cc: [{ display_name: 'Manager', Kennung: 'boss@acme.com' }], bcc: [{ display_name: 'Prüfung', Kennung: 'audit@internal.io' }, Betreff: 'Ihre Rechnung #1042', // HTML-Body – Anbieter rendert ihn nativ body: `

Rechnung #1042

Fälliger Betrag: $299

Jetzt bezahlen `
, }); Konsole.log('Gesendet:', result.tracking_id);
3
Vollbildreferenz
Alle unterstützten Parameter
FeldTypErforderlichBeschreibung
account_idZeichenketteErforderlichID des verknüpften E-Mail-Kontos, von dem gesendet werden soll
zuEmpfänger[]ErforderlichArray von {Anzeigename, Kennung} Objekte
ThemaZeichenketteErforderlichBetreffzeile der E-Mail
KörperZeichenketteErforderlichRein text oder HTML-String
ccEmpfänger[]OptionalKopienempfänger
BCCEmpfänger[]OptionalBcc-Empfänger
fromEmpfängerOptionalAbsendernamen überschreiben
antworten_aufZeichenketteOptionalAnbieter-Nachrichten-ID, auf die geantwortet werden soll (Threads)
AnhängeArrayOptionalArray von [Dateiname, Puffer] Tupel
benutzerdefinierte KopfzeilenObjekte[]OptionalBenutzerdefinierte X-Header-Array
Tracking-OptionenObjektOptional{öffnet, verknüpft, Kennzeichnung} - Öffnen/Klick-Tracking aktivieren
Kostenlos starten
Bereit, E-Mails über eine API in JavaScript zu versenden?

Holen Sie sich Ihren API-Schlüssel, verknüpfen Sie in wenigen Minuten ein Gmail- oder Outlook-Konto und führen Sie die Node.js-Beispiele aus diesem Leitfaden mit echten Postfächern aus.

Anhänge

Anhänge in Node.js senden

Die Anhänge Feld akzeptiert ein Array von [Dateiname, Puffer] Tuples. Lies die Datei mit Node's fs.readFileSync oder per Stream mit fs.promises.readFile.

Einzelne Datei von der Festplatte
Verwenden Sie fs.promises.readFile(pfad) um einen Puffer zu erhalten, dann weitergeben ['Dateiname.pdf', Puffer]. Funktioniert für PDF, DOCX, Bilder, jede Binärdatei.
Mehrere Anhänge
Ein Array von Tupeln übergeben. Jedes Tupel ist unabhängig - mischen Sie Dateitypen beliebig. Keine harte Obergrenze pro Anhang, aber halten Sie die gesamte Nutzlast unter dem Limit Ihres Plans.
Inline-Bilder (CID)
Bilder im HTML-Body mit dem folgenden einbetten cid: Schema. Verweisen Sie auf denselben Dateinamen, der im Tupel der Anhänge verwendet wird: <img src="cid:logo.png">.
Puffer aus einem Stream
PDFs im Handumdrehen generieren (z. B. mit pdfkit), sammle sie in einem Buffer und hänge sie an, ohne sie auf die Festplatte zu schreiben. Produktionssicher für Serverless.
Datei-anhängen.mjs
import { UnipileClient } from 'unipile-node-sdk'; import Versprechen als fs from 'node:fs'; const client = neu UnipileClient(process.env.UNIPILE_DSN, process.env.UNIPILE_TOKEN); // Datei in einen Puffer lesen const pdfPuffer = await fs.Datei lesen('./rechnung.pdf'); await client.email.senden.({ account_id: process.env.EMAIL_KONTO_ID, an: [{ display_name: 'Kunde', Kennung: 'client@example.com' }], Betreff: 'Ihre Rechnung ist beigefügt', body: '

Bitte finden Sie Ihre Rechnung beigefügt.

'
, Anhänge: [ ['Rechnung.pdf', pdfPuffer], // [Dateiname, Puffer] ], });
attach-multiple-inline.mjs
const [Logo, Bericht] = await Promise.allfs.Datei lesen('./logo.png'), fs.Datei lesen('./bericht.xlsx'), ]); await client.email.senden.({ account_id: process.env.EMAIL_KONTO_ID, an: [{ display_name: 'Mannschaft', Kennung: 'team@acme.com' }], Betreff: 'Q1-Bericht', body: Logo

Q1 Bericht

Siehe die angehängte Tabellenkalkulation für Details.

`
, Anhänge: [ ['Logo.png', Logo], // inline via cid:logo.png im Body ['Bericht.xlsx', Bericht], // regulärer Anhang ], });
Größenbeschränkung Halten Sie einzelne Anhänge unter 25 MB (Gmails harte Obergrenze). Bei großen Dateien laden Sie diese in einen Cloud-Speicher hoch und fügen stattdessen einen Download-Link in den E-Mail-Text ein.
Fortgeschrittene

Antworten, Threads & Nachverfolgung

Gehen Sie über einfache Sendungen hinaus: Thread-Antworten, benutzerdefinierte Header für Idempotenz, Open/Click-Tracking über Webhooks und E-Mails im Namen eines Benutzers senden.

1
Antwort auf einen Thread

Übergeben Sie die Provider-Nachrichten-ID (entweder aus der ursprünglichen Sendeantwort oder aus der Liste der E-Mails) als antworten_auf. Unipile stellt die richtige sicher Antwort auf und Referenzen Header, damit die Antwort-Threads in Gmail, Outlook und IMAP-Clients korrekt funktionieren.

Antwort-Thread.mjs
await client.email.senden.({ account_id: process.env.EMAIL_KONTO_ID, an: [{ display_name: 'Alice', Kennung: 'alice@acme.com' }], Betreff: 'Betreff: Ihre Frage', body: '

Vielen Dank für Ihre Nachricht! Hier ist die Antwort...

'
, // Provider-Nachrichten-ID aus der ursprünglichen E-Mail Antwort an: 'msg_xxxxxxxxxxxxxxxx', });
2
Benutzerdefinierte Header & Idempotenz

Verwenden Sie benutzerdefinierte Kopfzeilen hinzuzufügen X- Kopfzeile. Ein gängiges Muster ist X-Idempotenz-Schlüssel um doppelte Sendungen bei Wiederholungsversuchen nach einem Netzwerkausfall zu verhindern.

custom-headers.mjs
import { zufälligeUUID } from 'Knoten:Krypto'; await client.email.senden.({ account_id: process.env.EMAIL_KONTO_ID, an: [{ display_name: 'Bob', Kennung: 'bob@example.com' }], Betreff: 'Bestellbestätigung #9981', body: '

Ihre Bestellung ist bestätigt.

'
, benutzerdefinierte_header: [ { name: 'X-Idempotenz-Schlüssel', Wert: zufälligeUUID}, { name: 'X-Bestell-ID', Wert: '9981' }, ], });
3
Öffnungs- und Klickverfolgung über Webhooks

Tracking aktivieren in Tracking-Optionen. Unipile löst ein Webhook-Ereignis aus (E-Mail.geöffnet / E-Mail-Link angeklickt) an Ihre registrierte Webhook-URL mit dem Etikett Sie setzen es hier, damit Sie Ereignisse mit Ihren internen IDs korrelieren können.

tracking.mjs
await client.email.senden.({ account_id: process.env.EMAIL_KONTO_ID, an: [{ display_name: 'Blei', Kennung: 'lead@prospect.com' }], Betreff: 'Im Nachgang zu Ihrer Testversion', body: '

Hallo, ich wollte mal nachfragen...

'
, tracking_optionen: { opens: true, // löst den Webhook email.opened aus Links: true, // feuert den webhook email.link_clicked Etikett: 'crm_lead_12345', // Ihre interne Korrelations-ID }, });
4
Senden im Namen eines anderen Benutzers

Wenn Sie Multi-Tenant-SaaS-Anwendungen erstellen, verknüpft jeder Endbenutzer sein eigenes E-Mail-Konto. Speichern Sie die account_id pro Benutzer in Ihrer Datenbank und übergeben Sie ihn zum Sendezeitpunkt. Sehen Sie sich die vollständige Anleitung an So senden Sie eine E-Mail im Namen eines Benutzers.

in Vertretung.mjs
// Jeder Benutzer hat seine eigene verknüpfte account_id, die in Ihrer DB gespeichert ist async function sendAsUser(userId, an, Betreff, Nachricht) { const Benutzer = await Datenbank.Benutzer abrufen(BenutzerId); return client.email.senden.account_id: user.unipile_account_id, // pro Benutzer an, Betreff, Nachricht, }); } // E-Mail wird von Alices Gmail gesendet, nicht von unserer Serveradresse await sendAsUser('benutzer_alice', Empfänger, Betreff, Nachricht);

Arbeiten Sie stattdessen in Python? Sehen Sie unsere Python-Implementierung Leitfaden.

Produktionsreif

Fehlerbehandlung & Wiederholungsversuche

Netzwerkfehler und Ratenbegrenzungen sind im großen Maßstab unvermeidlich. Hier ist ein produktionsreifes Async/Await-Muster für Ihre JavaScript-Implementierung der E-Mail-Sende-API - mit exponentiellem Backoff und strukturiertem Logging unter Verwendung von Winston oder Pino.

202
Angenommen
E-Mail erfolgreich in die Warteschlange gestellt. Sendungs-ID ist gefüllt. Kein erneuter Versuch erforderlich.
429
Ratenbegrenzt
Too viele Anfragen. Beachten Sie die Erneut versuchen nach Header. Verwende exponentielle Backoff.
401
Nicht autorisiert
Ungültiger oder abgelaufener Token. Überprüfen Sie UNIPILE_TOKEN Umgebungsvariable. Nicht erneut versuchen – Anmeldeinformationen korrigieren.
422
Validierungsfehler
Fehlendes erforderliches Feld oder falsch formatierter Empfänger. Überprüfen Sie den Fehlertext – er gibt an, welches Feld fehlgeschlagen ist.
503
Dienst nicht verfügbar
Vorübergehender Serverfehler. Sicher, es mit Backoff erneut zu versuchen. Überprüfen Sie status.unipile.com auf Vorfälle.
404
Konto nicht gefunden
Die account_id existiert nicht oder wurde widerrufen. Verknüpfen Sie das Konto erneut.
Exponentielles Backoff mit async/await
senden-mit-wiederholung.mjs
import { UnipileClient } from 'unipile-node-sdk'; import logger from './logger.mjs'; // Winston or Pino instance const client = new UnipileClient(process.env.UNIPILE_DSN, process.env.UNIPILE_TOKEN); async function sendWithRetry(payload, maxAttempts = 4) { let attempt = 0; while (attempt < maxAttempts) { try { const result = await client.email.send(payload); logger.info({ tracking_id: result.tracking_id }, 'Email sent'); return result; } catch (err) { const status = err?.status ?? err?.statusCode; // Do not retry on client errors (4xx except 429) if (status >= 400 && status !== 429 && status < 500) { logger.error({ status, err }, 'Non-retryable error'); throw err; } attempt++; if (attempt >= maxAttempts) throw err; // Exponential backoff: 1s, 2s, 4s, 8s... const delay = 1000 * 2 ** (attempt - 1); logger.warn({ attempt, delay, status }, 'Retrying...'); await new Promise(r => setTimeout(r, delay)); } } } // Usage await sendWithRetry({ account_id: process.env.EMAIL_ACCOUNT_ID, to: [{ display_name: 'User', identifier: 'user@example.com' }], subject: 'Your report is ready', body: '

Click to download.

'
, });
Sicherheit

Sicherheitsbest Practices in Node.js

Ihr UNIPILE_TOKEN gewährt vollen API-Zugriff. Niemals clientseitig freigeben. Vollständige Informationen siehe E-Mail-API-Sicherheitsleitfaden für fortgeschrittene Themen, einschließlich DKIM, SPF und OAuth-Token-Rotation.

Schlüssel niemals auf der Clientseite preisgeben
Ihr UNIPILE_TOKEN muss auf dem Server bleiben. Jedes browserseitige JavaScript – einschließlich Next.js Client-Komponenten, React-Frontend oder Vite – darf das Token NICHT direkt importieren.
Verwenden Sie eine Backend-Proxy-Route
In Next.js eine API-Route erstellen (/api/email-senden). In Express, ein POST-Endpunkt. Authentifizieren Sie zuerst Ihre eigenen Benutzer und rufen Sie dann Unipile serverseitig mit dem Token aus der Umgebung auf.
OAuth-Aktualisierungstoken
Unipile verwaltet das automatische Aktualisieren von Gmail- und Outlook-OAuth-Token. Ihre gespeicherten account_id bleibt gültig. Sie müssen die Ablaufzeit des Zugriffstokens nicht selbst verwalten.
DKIM und SPF (Absenderreputation)
E-Mails, die über verknüpfte Gmail/Outlook-Konten gesendet werden, übernehmen die DKIM-Signaturen dieser Anbieter. Für IMAP/SMTP-Konten konfigurieren Sie DKIM auf Ihrem Mailserver, bevor Sie die Verknüpfung herstellen.
Empfänger-Eingabe validieren
Wenn Empfänger aus Benutzereingaben stammen, validieren Sie das E-Mail-Format serverseitig, bevor Sie die API aufrufen. Die API lehnt fehlerhafte Adressen mit einem 422 ab, aber eine Validierung vor dem Aufruf führt zu klareren UX-Fehlern.
API-Token nach Umgebung filtern
Verwenden Sie separate Unipile-Projekte (und Tokens) für Entwicklung, Staging und Produktion. Dies verhindert, dass Test-E-Mails an echte Benutzer gesendet werden, und begrenzt den potenziellen Schaden, falls ein Schlüssel kompromittiert wird.
FALSCH Token im Frontend-Code
// client.js - NIEMALS so etwas tun const client = new UnipileClient( 'https://api4.unipile.com:13444', 'sk_live_xxxxxxxxxx' aufgeflogen! );
KORREKT Backend-Proxy-Route (Next.js)
// app/api/send-email/route.js exportiere asynchron POST(req) { // zuerst Authentifizierungsprüfung const session = await getServerSession(); if (!session) return new Response(null,{status:401}); const client = new UnipileClient( process.env.UNIPILE_DSN, // nur auf dem Server process.env.UNIPILE_TOKEN // nur auf dem Server ); await client.email.send({...}); }
Vollständige Anleitung zur E-Mail-API-Sicherheit lesen
Häufige Fehler

Häufige Fallstricke (Node.js-spezifisch)

Dies sind die häufigsten Fehler, die Entwickler machen, wenn sie zum ersten Mal eine E-Mail-API in JavaScript integrieren. Jeder einzelne ist leicht zu vermeiden, sobald man das Muster kennt – und alle gelten gleichermaßen für den Kontext der Node.js-E-Mail-API.

1
Das Vergessen von Top-Level-Await (CommonJS vs. ESM)
Oberste Ebene await funktioniert nur in ES-Modulen (.mjs oder "type":"module"). In CommonJS, verpacken Sie Ihren Send-Aufruf in einen asynchron IIFE oder verwenden .dann(). Das SDK funktioniert in beiden – wählen Sie einfach das richtige Modulformat aus.
cjs-workaround.cjs
// CommonJS: in asynchrone IIFE einpacken (asynchron () => { const { UnipileClient } = await import('unipile-node-sdk'); const client = neu UnipileClient(process.env.UNIPILE_DSN, process.env.UNIPILE_TOKEN); await client.email.senden.({ /* ... */ }); })();
2
Promise.all für Massensendungen ohne Berücksichtigung von Ratenbegrenzungen
1.000 feuern Promise.all gleichzeitig gesendet werden, wird die Ratenbegrenzung erreicht und 429-Fehler verursacht. Verwenden Sie einen Gleichzeitigkeitsbegrenzer wie p-Grenze um parallele Anfragen zu begrenzen.
bulk-send.mjs
import pLimit from 'p-Limit'; const Grenze = pLimit(5); // max. 5 gleichzeitige Sendeoperationen const Ergebnisse = await Promise.allEmpfänger.Karte(r => Grenze(() => client.email.senden.({ account_id: process.env.EMAIL_KONTO_ID, { zu: [r], Betreff, Text, }))) );
3
Falsche Buffer-Kodierung für Anhänge
Immereinen Rohwert übergeben Puffer Objekt – keine Base64-Zeichenkette, keine UTF-8-Zeichenkette. Wenn Sie Base64-Inhalte haben (z. B. von einem Webhook oder einer API-Antwort), konvertieren Sie diese zuerst: Buffer.from(base64str, 'base64').
buffer-encoding.mjs
// FALSCH: Übergabe eines Strings Anhänge: [['Datei.pdf', 'JVBERi0xLjQ...']] // Base64-String – kaputt! // KORREKT: Pufferobjekt Anhänge: [['Datei.pdf', Puffer.from(base64str, 'base64')]] // oder von der Festplatte: Anhänge: [['Datei.pdf', await fs.Datei lesen('./file.pdf')]]
4
Unerwartete Promise-Ablehnungen führen zum Absturz des Prozesses
In Node.js wird eine nicht abgefangene Ablehnung in einer "fire-and-forget"- send() Aufruf wird den Prozess in Node 15+ abstürzen lassen. Immer await das Ergebnis oder anhängen .catch() Bearbeitungsroutine.
unhandled-rejection.mjs
// FALSCH: Fire-and-Forget – stürzt bei Fehlern in Node 15+ ab client.email.senden.(Nutzlast); // kein await, kein .catch() // KORREKT: Versprechen immer behandeln await client.email.senden.(Nutzlast) // Option 1: await .fangen(Fehler => Protokollierer.Fehler(err)); // Option 2: .catch()
5
Diese API direkt in Browser-JavaScript verwenden
Das Unipile SDK und Ihr UNIPILE_TOKEN sind nur für serverseitiges Node.js. Der direkte Browser-Fetch zur API würde Ihr Token preisgeben. Verwenden Sie eine Backend-Route (Next.js API-Route, Express-Endpunkt, Netlify/Vercel-Funktion) als Proxy.
6
Senden ohne verknüpftes Konto (account_id fehlt)
Sie können nicht von einer generischen Adresse senden – jeder Sendeauftrag muss sich auf eine gültige beziehen account_id von einem zuvor verknüpften Gmail-, Outlook- oder IMAP-Konto. Die API gibt 404 zurück, wenn die account_id fehlt oder entkoppelt wurde.

Häufig gestellte Fragen

Häufig gestellte Fragen zum Senden von E-Mails in JavaScript und Node.js mit der Unipile Unified Email API.

Verwenden Sie die Unipile Unified Email API anstelle einer direkten SMTP-Verbindung. Installieren Sie unipile-node-sdk, initialisieren UnipileClient Mit Ihrer DSN und dem Token verknüpfen Sie ein Gmail- oder Outlook-Konto über OAuth und rufen dann auf client.email.sende(). Kein SMTP-Server, kein Port 587, keine TLS-Konfiguration auf Ihrer Seite erforderlich – Unipile kümmert sich um die Transportschicht.

Nein – und das sollten Sie auch nicht. Der Aufruf der Unipile API aus JavaScript im Browser würde Ihr UNIPILE_TOKEN an jeden Benutzer, der DevTools öffnet. Rufen Sie die API immer aus einem serverseitigen Node.js-Kontext auf: einer Express-Route, einer Next.js-API-Route (app/api/), eine Vercel Edge Function oder eine Netlify Function.

Ihr Frontend sendet eine Anfrage an Ihren eigenen Backend-Endpunkt, der die Benutzersitzung authentifiziert und dann den Unipile-Server aufruft.

Nodemailer verbindet sich direkt mit einem SMTP-Server aus Ihrem Node.js-Prozess. Es erfordert, dass Sie SMTP-Anmeldeinformationen verwalten, TLS behandeln, DKIM selbst konfigurieren und sich separat mit den Eigenheiten jedes Anbieters auseinandersetzen.

Die Unipile E-Mail-API ist eine Cloud-Abstraktionsschicht: Sie verbinden Konten über OAuth (keine SMTP-Zugangsdaten für Gmail/Outlook erforderlich), erhalten ein einheitliches SDK für alle Anbieter und Unipile kümmert sich um Transport, Wiederholungsversuche und Token-Aktualisierung. Der Kompromiss besteht darin, dass Ihre Sendungen über die Infrastruktur von Unipile und nicht über eine direkte SMTP-Verbindung erfolgen.

Ja. Die unipile-node-sdk Pakete mit TypeScript-Typdefinitionen. Sie erhalten vollständige Autovervollständigung und Typsicherheit für das send() Nutzlast, einschließlich Empfänger, Tracking-Optionen, und der Antworttyp.

import { UnipileClient } from 'unipile-node-sdk'; // Vollständige TS-Typen – Autovervollständigung funktioniert in VSCode const Kunde UnipileClient = neu UnipileClient(dsn, token); const Ergebnis = await client.email.senden.({ /* eingegeben! */ });

Für Massensendungen verwenden Sie einen Gleichzeitigkeitsbegrenzer (z.B. p-Grenze mit 5-10 gleichzeitigen Aufrufen), fügen Sie exponentielles Backoff bei 429-Antworten hinzu und verteilen Sie die Sendungen nach Möglichkeit auf mehrere verknüpfte Konten. Jedes verknüpfte E-Mail-Konto hat seine eigenen schreibenden Limits, die vom Anbieter festgelegt werden (Gmail: ~500/Tag für normale Konten, höher für Workspace).

Für echte Massen-/Marketing-E-Mails im großen Stil (Millionen von Empfängern) sollten Sie einen dedizierten ESP (Mailgun, SendGrid) neben Unipile für transaktionale und OAuth-basierte Sendungen in Betracht ziehen.

Next.js: API-Routen verwenden (app/api/send-email/route.jsoder Server Actions. Die SDK-Instanziierung sollte ausschließlich serverseitig erfolgen.

Nuxt: Server-Routen verwendenserver/api/send-email.post.ts). Das SDK ist nur für Node.js verfügbar und kann daher nicht in ein Composable oder Plugin integriert werden, das auf dem Client läuft.

NestJS: erstellen E-MailModul mit einem Dienst, der umhüllt UnipileClient. Injizieren Sie es, wo immer Sie Sendeaktionen auslösen müssen – in Controllern, CRON-Jobs oder Ereignisbehandlern.

Haben Sie noch Fragen? Unser Team ist für Sie da.

de_DEDE