LinkedIn
Instagram
WhatsApp
Telegram
Google Agenda
Word lid van de Slack-gemeenschapHoe te E-mail verzenden via API in JavaScript (Node.js-handleiding)
Sla de SMTP-standaardtekst over. Deze handleiding laat zien hoe je e-mail verzendt in Node.js met behulp van de Unipile uniforme e-mail API - met copy-paste code voor Gmail, Outlook en SMTP in minder dan 10 regels JavaScript.
importeer { UnipileClient } van 'unipile-node-sdk';
const klant = nieuw UnipileClient(
proces.env.UNIPILE_DSN,
process.env.UNIPILE_TOKEN
);
wacht op client.e-mail.verzenden({
account_id: 'UW_ACCOUNT_ID',
aan: [{ display_name: 'Alice',
identificatiecode: 'alice@example.com' }],
onderwerp: 'Hallo vanuit Node.js',
body: 'Verzonden via Unipile!
'
});
Node.js-voorbeeld van 5 regels
Als je al weet wat een Verzend e-mail API is en wil gewoon een e-mail API JavaScript-code meesturen die daadwerkelijk werkt, hier is hij. De volledige tutorial volgt hieronder.
npm installeer unipile-node-sdkUNIPILE_DSN en UNIPILE_TOKEN naar jou .env bestand.client.email.verstuur()account_id, naar, onderwerpen lichaam. Klaar.importeer { UnipileClient } van 'unipile-node-sdk';
const klant = nieuw UnipileClient(
proces.env.UNIPILE_DSN,
process.env.UNIPILE_TOKEN
);
const resultaat = wachten client.e-mail.verzenden({
account_id: 'acc_xxxxxxxxxxxxxxxx',
naar: [{
weergavenaam: 'Alice Martin',
identificatie: 'alice@acme.com'
}],
onderwerp: 'Hallo vanuit Node.js',
body: 'Verzonden via Unipile API!
'
});
console.log(resultaat); // { tracking_id: 'msg_...' }Vereisten en installatie
Voordat u de JavaScript-workflow van de send email API in productie kunt gebruiken, heeft u vier dingen nodig: een ondersteunde Node.js-versie, de Unipile SDK, een API-sleutel en een DSN-eindpunt.
fetch en topniveau wacht op. Node 20 LTS wordt aanbevolen voor productie. Controleer uw versie met node -v.api4.unipile.com:13444Beide zijn vereist om de client te initialiseren..mjs bestanden of set "type":"module" in pakket.json. Voor CommonJS, dynamisch import() werkt ook - voorbeelden hieronder getoond.npm installeer unipile-node-sdkyarn add unipile-node-sdkpnpm add unipile-node-sdk# Unipile-gegevens (commit dit bestand nooit)
UNIPILE_DSN=https://api4.unipile.com:13444
UNIPILE_TOKEN=uw_toegangstoken_hier
# Het account-ID van het gekoppelde e-mailaccount
EMAIL_ACCOUNT_ID=acc_xxxxxxxxxxxxxxxxToevoegen .env naar jou .gitignore. Gebruik dotenv of de native Node 20.6+ --omgevingsbestand vlag om het te laden: node --env-file=.env send.mjs.
Uw eerste e-mailaccount verbinden
De unificerende e-mail-API gebruikt een enkel account_id om providerverschillen te abstraheren. Koppel een account één keer, bel vervolgens client.email.verstuur() identiek over alle drie de providers.
Kies hieronder uw provider om het exacte Node.js-fragment te zien. De geretourneerde account_id is wat u opslaat en hergebruikt voor elke volgende verzending.
Gmail OAuth
Outlook / Microsoft 365
SMTP / IMAP
importeer { UnipileClient } van 'unipile-node-sdk';
const klant = nieuw UnipileClientprocess.env.UNIPILE_DSN, process.env.UNIPILE_TOKEN);
// Stap 1: Genereer een gehoste OAuth-link voor Gmail
const { url } = wachten account van de cliënt.maakHostedAuthLink({
type: 'GOOGLE',
success_redirect_url: process.env.OAUTH_CALLB ACK_URL,
failure_redirect_url: process.env.OAUTH_CALLB ACK_URL + '?error=1',
});
// Stap 2: herlei je gebruiker naar `url`
console.log('Gebruiker doorverwijzen naar:', url);
// Stap 3: Unipile POST de account_id naar je callback
// Sla het op: process.env.EMAIL_ACCOUNT_ID = result.account_idimporteer { UnipileClient } van 'unipile-node-sdk';
const klant = nieuw UnipileClientprocess.env.UNIPILE_DSN, process.env.UNIPILE_TOKEN);
// Werkt voor persoonlijke Outlook EN Microsoft 365 / Exchange Online
const { url } = wachten account van de cliënt.maakHostedAuthLink({
type: 'MICROSOFT',
success_redirect_url: process.env.OAUTH_CALLB ACK_URL,
failure_redirect_url: process.env.OAUTH_CALLB ACK_URL + '?error=1',
});
// Gebruiker omleiden -> ze voltooien de Microsoft OAuth-stroom
console.log('Gebruiker doorverwijzen naar:', url);
// Zie: /syncing-emails-with-microsoft-graph-api-a-developers-guide/importeer { UnipileClient } van 'unipile-node-sdk';
const klant = nieuw UnipileClientprocess.env.UNIPILE_DSN, process.env.UNIPILE_TOKEN);
// SMTP/IMAP: referenties direct doorgeven (geen OAuth-omleiding)
const account = wachten account van de cliënt.create({
type: 'IMAP',
imap: {
username: process.env.IMAP_GEBRUIKER,
wachtwoord: process.env.IMAP_WACHTWOORD, host: process.env.IMAP_HOST,
poort: 993,
},
smtp: {
username: process.env.IMAP_GEBRUIKER,
wachtwoord: process.env.IMAP_WACHTWOORD, host: process.env.SMTP_HOST,
poort: 587,
},
});
console.log(account.account_id); // dit opslaan
Gmail
Outlook / Microsoft 365
SMTP / IMAP
Uw eerste e-mail verzenden vanuit Node.js
Drie productierijpe patronen voor de JavaScript-workflow van de send email API: platte tekst, HTML met CC/BCC, en het lezen van het response object. Alle gebruiken dezelfde client.email.verstuur() bel.
importeer { UnipileClient } van 'unipile-node-sdk';
const klant = nieuw UnipileClientprocess.env.UNIPILE_DSN, process.env.UNIPILE_TOKEN);
const resultaat = wachten client.e-mail.verzendenaccount_id: process.env.EMAIL_ACCOUNT_ID,
aan: [{ display_name: 'Bob', identificatie: 'bob@example.com' }],
onderwerp: 'Welkom op het platform',
body: 'Hoi Bob, je account is klaar.',
});
console.log(result.tracking_id); // msg_xxxxxxxxxxxxxxxxconst resultaat = wachten client.e-mail.verzendenaccount_id: process.env.EMAIL_ACCOUNT_ID,
aan: [{ display_name: 'Alice', identifier: 'alice@acme.com' }],
cc: [{ display_name: 'Manager', identificatie: 'boss@acme.com' }],
bcc: [{ display_name: 'Audit', identifier: 'audit@internal.io' }},
onderwerp: 'Uw factuur #1042',
// HTML body - provider rendert het native
body: `
Factuur #1042
Te betalen bedrag: $299
Betaal nu
`,
});
console.log('Verzonden:', result.tracking_id);| Veld | Type | Vereist | Beschrijving |
|---|---|---|---|
account_id | snaar | Vereist | ID van het gekoppelde e-mailaccount om van te verzenden |
naar | Ontvanger[] | Vereist | Array van {weergavenaam, identificatie} voorwerpen |
onderwerp | snaar | Vereist | Onderwerp van de e-mail |
lichaam | snaar | Vereist | Platte tekst of HTML-string |
cc | Ontvanger[] | Optioneel | CC-ontvangers |
cc | Ontvanger[] | Optioneel | Blinde kopie ontvangers |
van | Ontvanger | Optioneel | Verzendernaam negeren |
antwoord_op | snaar | Optioneel | Provider bericht ID om op te antwoorden (threads) |
bijlagen | Array | Optioneel | Array van [bestandsnaam, Buffer] tuples |
aangepaste_headers | object[] | Optioneel | Aangepaste X-headers-array |
tracking_opties | voorwerp | Optioneel | {opent, koppelt, label} - open/klikregistratie inschakelen |
Verkrijg je API-sleutel, koppel een Gmail- of Outlook-account in enkele minuten en voer de Node.js-voorbeelden uit deze handleiding uit op echte postbussen.
Bijlagen verzenden in Node.js
De bijlagen veld accepteert een array van [bestandsnaam, Buffer] tuples. Lees het bestand met Node's fs.readFileSync of stream het met fs.promises.readFile.
fs.promises.readFile(pad) om een Buffer te krijgen, dan door te geven ['achternaam.pdf', buffer]. Werkt voor PDF, DOCX, afbeeldingen, elke binaire.cid: schema. Verwijs naar dezelfde bestandsnaam die in de bijlagentuple wordt gebruikt: <img src="cid:logo.png">.pdfkit), verzamel het in een Buffer en voeg het toe zonder het naar schijf te schrijven. Productieklaar voor serverless.importeer { UnipileClient } van 'unipile-node-sdk';
importeer beloften als fs } van 'node:fs';
const klant = nieuw UnipileClientprocess.env.UNIPILE_DSN, process.env.UNIPILE_TOKEN);
// Bestandsinhoud lezen in een Buffer
const pdfBuffer = wachten fs.leesBestand('./factuur.pdf');
wacht op client.e-mail.verzendenaccount_id: proces.env.EMAIL_ACCOUNT_ID,
aan: [{ display_name: 'Klant', identificatie: 'client@example.com' }],
onderwerp: 'Uw factuur is bijgevoegd',
body: 'U vindt uw factuur bijgevoegd.
',
bijlagen: [
['factuur.pdf', pdfBuffer], // [bestandsnaam, Buffer]
],
});const [logo, rapport] = wachten Promise.all([
fs.leesBestand('./logo.png'),
fs.leesBestand('./report.xlsx'),
]);
wacht op client.e-mail.verzendenaccount_id: process.env.EMAIL_ACCOUNT_ID,
naar: [{ display_name: 'Team', identificatie: 'team@acme.com' }],
onderwerp: 'Kwartaal 1 Rapport',
body: 
Q1 Rapport
Zie het bijgevoegde spreadsheet voor details.
`,
bijlagen: [
['logo.png', logo], // inline via cid:logo.png in body
['rapport.xlsx', rapport], // standaard bijlage
],
});Antwoorden, Threads & Tracking
Ga verder dan basisverzendingen: threadreacties, aangepaste headers voor idempotentie, open-/kliktracking via webhooks, en e-mail verzenden namens een gebruiker.
1
Reageren op een thread
Geef de provider bericht ID (teruggegeven in het oorspronkelijke send response of uit het opsommen van e-mails) door als antwoord_op. Unipile injecteert het juiste In-Reply-To en Referenties headers zodat het antwoord correct wordt gethread in Gmail, Outlook en IMAP-clients.
wacht op client.e-mail.verzendenaccount_id: process.env.EMAIL_ACCOUNT_ID,
naar: [{ display_name: 'Alice', identificatie: 'alice@acme.com' }],
onderwerp: 'Re: Uw vraag',
body: 'Bedankt voor uw bericht! Hier is het antwoord...
',
// Provider bericht-ID van de originele e-mail
reageren_op: 'bericht_xxxxxxxxxxxxxxxx',
});
2
Aangepaste headers en idempotentie
Gebruik aangepaste_headers toe te voegen X- header. Een veelvoorkomend patroon is X-Idempotency-Sleutel om dubbele verzendingen te voorkomen bij het opnieuw proberen na een netwerktime-out.
importeer { willekeurigeUUID } van 'knooppunt:crypto';
wacht op client.e-mail.verzendenaccount_id: process.env.EMAIL_ACCOUNT_ID,
naar: [{ display_name: 'Bob', identificatie: 'bob@example.com' }],
onderwerp: 'Orderbevestiging #9981',
body: 'Uw bestelling is bevestigd.
',
custom_headers: [
{ naam: 'X-Idempotentie-Sleutel', waarde: willekeurigeUUID},
{ naam: 'X-Order-ID', waarde: '9981' },
],
});
3
Open- en kliktracking via webhooks
Inschakelen van tracking in tracking_opties. Unipile vuurt een webhook-gebeurtenis af (e-mail.geopend / email.link_aangeklikt) naar uw geregistreerde webhook-URL met de etiket Je stelt hier in zodat je gebeurtenissen kunt correleren met je interne ID's.
wacht op client.e-mail.verzendenaccount_id: process.env.EMAIL_ACCOUNT_ID,
naar: [{ display_name: 'Lood', identificatie: 'lead@prospect.com' }],
onderwerp: 'Opvolging van uw proefperiode',
body: 'Hallo, wilde even informeren...
',
tracking_opties: {
opens: true, // vuurt webhook email.opened af
links: true, // vuurt email.link_clicked webhook af
etiket 'crm_lead_12345', // je interne correlatie-ID
},
});
4
Verzenden namens een andere gebruiker
Bij het bouwen van multi-tenant SaaS-apps koppelt elke eindgebruiker zijn eigen e-mailaccount. Sla de op account_id per gebruiker in uw database en geef deze mee bij het verzenden. Zie de volledige gids op hoe e-mail te verzenden namens een gebruiker.
// Elk gebruikersaccount heeft zijn eigen gekoppelde account_id dat is opgeslagen in je database
async function stuurAlsGebruiker(gebruikerId, aan, onderwerp, bericht) {
const gebruiker = wachten db.GebruikerOphalen(gebruikersId);
return client.e-mail.verzendenaccount_id: user.unipile_account_id, // per-gebruiker
aan, onderwerp, inhoud,
});
}
E-mail wordt verzonden vanaf Alice's Gmail, niet vanaf uw serveradres
wacht op stuurAlsGebruiker('gebruiker_alice', ontvangers, onderwerp, inhoud);Werk je liever in Python? Zie onze Python-implementatie gids.
Foutafhandeling en Opnieuw proberen
Netwerkfouten en snelheidslimieten zijn onvermijdelijk op schaal. Hier is een productieklare async/await-patroon voor uw send email API JavaScript-implementatie - met exponentiële backoff en gestructureerd loggen met Winston of Pino.
tracking_id wordt gevuld. Geen herhaling nodig.Opnieuw-Proberen-Na Koptekst. Gebruik exponentiële backoff.UNIPILE_TOKEN omgevingsvariabele. Probeer niet opnieuw - corrigeer inloggegevens.account_id bestaat niet of is ingetrokken. Koppel de account opnieuw.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.
',
});Beveiligingsprincipes in Node.js
Jouw UNIPILE_TOKEN verleent volledige API-toegang. Stel deze nooit bloot aan de clientzijde. Zie de volledige e-mail API beveiligingshandleiding voor geavanceerde onderwerpen, waaronder DKIM, SPF en rotatie van OAuth-tokens.
UNIPILE_TOKEN moet op de server blijven. Elke browser-side JavaScript - inclusief Next.js clientcomponenten, React-frontend of Vite - mag de token NIET rechtstreeks importeren./api/e-mail-verzenden. In Express, een POST-endpoint. Authenticeer eerst je eigen gebruikers, roep daarna Unipile server-side aan met de token uit de omgeving.account_id blijft geldig. U hoeft geen rekening te houden met het verlopen van uw toegangstoken.// client.js - DOE DIT NOOIT
const client = new UnipileClient(
'https://api4.unipile.com:13444',
'sk_live_xxxxxxxxxx' ontdekt!
);
// app/api/send-email/route.js
exporteer asynchroon functie POST(req) {
// controleer eerst authenticatie
const session = wacht op getServerSession();
if (!session) return new Response(null,{status:401});
const client = new UnipileClient(
process.env.UNIPILE_DSN, // alleen server
proces.env.UNIPILE_TOKEN // alleen server
);
wacht op client.email.send({...});
}
Veelvoorkomende valkuilen (Node.js-specifiek)
Dit zijn de meest voorkomende fouten die ontwikkelaars maken bij het voor de eerste keer integreren van een e-mail-API in JavaScript. Elk van deze fouten is gemakkelijk te vermijden zodra je het patroon kent - en ze zijn allemaal evenzeer van toepassing op de context van de Node.js e-mail-API.
wacht op werkt alleen in ES-modules.mjs of "type":"module". In CommonJS, omhul je send-aanroep met een asynchroon IIFE of gebruik .dan(). De SDK werkt in beide - kies gewoon het juiste moduleformaat.// CommonJS: omhullen met async IIFE
(asynchroon () => {
const { UnipileClient } = wachten importeer('unipile-node-sdk');
const klant = nieuw UnipileClientprocess.env.UNIPILE_DSN, process.env.UNIPILE_TOKEN);
wacht op client.e-mail.verzenden({ /* ... */ });
})();Promise.all gelijktijdig verzenden zal snelheidslimieten raken en 429-fouten veroorzaken. Gebruik een gelijktijdigheidslimiter zoals p-limiet om parallelle aanvragen te beperken.importeer pLimiet van 'p-limiet';
const begrenzen = pLimiet(5); // max 5 gelijktijdige verzendingen
const resultaten = wachten Promise.allontvangers.kaartr => begrenzen(() => client.e-mail.verzendenaccount_id: process.env.EMAIL_ACCOUNT_ID,
aan: [r], onderwerp, body,
})))
);Buffer object - geen base64-tekenreeks, geen UTF-8-tekenreeks. Als je base64-inhoud hebt (bijvoorbeeld van een webhook of API-antwoord), converteer deze dan eerst: Buffer.from(base64str, 'base64').// FOUT: een string doorgeven
bijlagen: [['bestand.pdf', 'JVBERi0xLjQ0...']] // base64 string - breekt!
// CORRECT: Bufferobject
bijlagen: [['bestand.pdf', Buffer.van(base64-string, "base64)]]
// of vanaf schijf:
bijlagen: [['bestand.pdf', wacht op fs.leesBestand('./bestand.pdf')]]verstuur() call zal het proces in Node 15+ laten crashen. Altijd wacht op het resultaat of bijvoegen een .catch() afhandelaar.// FOUT: fire-and-forget - crasht bij een fout in Node 15+
client.e-mail.verzenden(lading); // geen await, geen .catch()
// CORRECT: handel het promise altijd af
wacht op client.e-mail.verzenden(lading) // optie 1: await
.vangst(fout => logger.fout(err)); // optie 2: .catch()UNIPILE_TOKEN zijn alleen voor server-side Node.js. Browser fetch rechtstreeks naar de API zou uw token blootstellen. Gebruik een backend-route (Next.js API-route, Express-endpoint, Netlify/Vercel-functie) als proxy.account_id van een eerder gekoppeld Gmail-, Outlook- of IMAP-account. De API retourneert 404 als de account_id ontbreekt of is ontkoppeld.Veelgestelde vragen
Veelgestelde vragen over het verzenden van e-mail in JavaScript en Node.js met de Unipile unified email API.
unipile-node-sdk, initialiseren UnipileClient met uw DSN en token, koppel een Gmail- of Outlook-account via OAuth, en roep dan aan client.email.verstuur(). Geen SMTP-server, geen poort 587, geen TLS-configuratie nodig van uw kant - Unipile regelt de transportlaag.Nee - en dat zou je ook niet moeten doen. Het aanroepen van de Unipile API vanuit browser JavaScript zou je UNIPILE_TOKEN aan elke gebruiker die DevTools opent. Roep de API altijd aan vanuit een server-side Node.js-context: een Express-route, een Next.js API-route (app/api/), een Vercel Edge Function of een Netlify Function.
Je frontend stuurt een verzoek naar je eigen backend-eindpunt, dat de gebruikerssessie authenticeert en vervolgens de Unipile-server aanroept.
Nodemailer maakt rechtstreeks verbinding met een SMTP-server vanuit uw Node.js-proces. Het vereist dat u zelf SMTP-gegevens beheert, TLS afhandelt, DKIM configureert en apart omgaat met de eigenaardigheden van elke provider.
De Unipile e-mail API is een cloud-abstractielaag: u koppelt accounts via OAuth (geen SMTP-gegevens nodig voor Gmail/Outlook), krijgt één consistente SDK voor alle providers, en Unipile regelt transport, retries en tokenverversing. De afweging is dat uw verzendingen via de infrastructuur van Unipile lopen in plaats van via een directe SMTP-verbinding.
Ja. De unipile-node-sdk pakket schepen met TypeScript-type definities. Je krijgt volledige autocomplete en typeveiligheid voor de verstuur() lading, inclusief Ontvanger, tracking_opties, en het antwoordtype.
importeer { UnipileClient } van 'unipile-node-sdk';
// Volledige TS-typen - autocomplete werkt in VSCode
const klant: UnipileClient = nieuw UnipileClient(dsn, token);
const resultaat = wachten client.e-mail.verzenden({ /* getypt! */ });Voor verzendingen met hoge volumes, gebruik een concurrency limiter (bijv. p-limiet met 5-10 gelijktijdige oproepen), voeg exponentiële backoff toe voor 429-antwoorden, en spreid het versturen over meerdere gekoppelde accounts indien mogelijk. Elk gekoppeld e-mailaccount heeft zijn eigen verzendlimieten ingesteld door de provider (Gmail: ~500/dag voor reguliere accounts, hoger voor Workspace).
Voor echte bulk-/marketing-e-mails op schaal (miljoenen ontvangers), overweeg een speciale ESP (Mailgun, SendGrid) naast Unipile voor transactionele en OAuth-gebaseerde verzendingen.
Volgende.js: gebruik API-routesapp/api/e-mail-verzenden/route.js) of Server Actions. Houd de SDK-instantie alleen aan de serverzijde.
Nuxt. gebruik serverroutes (server/api/send-email.post.tsDe SDK is alleen voor Node.js, dus deze kan niet worden gebruikt in een composable of plugin die op de client draait.
NestJS: creëer een E-mailModule met een service die omhult UnipileClient. Injecteer het waar u verzendsignalen wilt activeren - in controllers, CRON-taken of gebeurtenisafhandelaars.
Heb je nog vragen? Ons team staat klaar om te helpen.
NL 
EN 
FR 
ES 
DE 
IT 
BR 
PL 
TR