Jak wysłać e-mail przez API w JavaScript (poradnik Node.js)

Spis treści
Spis treści 14 sekcji
Pierwsze kroki
Wysyłanie e-maili
Produkcja
Odniesienie
Samouczek JavaScript

Jak Wyślij e-mail przez API w JavaScript (Samouczek Node.js)

Pomiń standardowe teksty SMTP. Ten przewodnik pokazuje, jak wysyłać e-maile w Node.js za pomocą Unipile ujednolicone API poczty e-mail z kodem do kopiowania i wklejania dla Gmail, Outlook i SMTP w mniej niż 10 linijkach JavaScript.

API do wysyłania e-maili w JavaScript node.js API do wysyłania wiadomości e-mail Gmail / Outlook / SMTP ESM + async/await
wyślijE-mail.mjs
import { UnipileClient } z 'unipile-node-sdk'; const klient = nowy UnipileClientprocess.env.UNIPILE_DSN, process.env.UNIPILE_TOKEN ); czekać client.email.wysyłać({ account_id: 'IDENTYFIKATOR_TWOJEGO_KONTA', do: [{ display_name: 'Alicja', identyfikator: 'alice@example.com' }], temat: 'Cześć z Node.js', body: '

Wysłano przez Unipile!

'
});
Email dostarczony - 202 Zaakceptowano
Współpracuje z: Gmail Perspektywy IMAP
W skrócie

5-wierszowy przykład Node.js

Jeśli już wiesz, czym jest API wysyłania wiadomości e-mail i i po prostu chcę wysłać kod API JavaScript do obsługi poczty e-mail, który faktycznie działa, oto on. Pełny tutorial znajduje się poniżej.

1
Zainstaluj SDK
npm install unipile-node-sdk
2
Ustaw zmienne środowiskowe
Dodaj UNIPILE_DSN oraz UNIPILE_TOKEN do twojego .env plik.
3
Połącz konto e-mail
OAuth dla Gmail/Outlook lub poświadczenia SMTP dla dowolnego serwera IMAP - jedno wywołanie API.
4
Zadzwoń client.email.send()
Podanie account_id, do, podmiotoraz ciało. Zrobione.
Ten sam kod działa dla Gmail, Outlook i każdego serwera IMAP – nie potrzebna żadna logika specyficzna dla dostawcy. Sprawdź Przewodnik po API poczty elektronicznej po pełny przegląd koncepcji.
send.mjs
import { UnipileClient } z 'unipile-node-sdk'; const klient = nowy UnipileClientprocess.env.UNIPILE_DSN, process.env.UNIPILE_TOKEN ); const wynik = await client.email.wysyłać({ account_id: 'acc_xxxxxxxxxxxxxxxx', do: [{ nazwa_wyswietlana: 'Alicja Martin', identyfikator: 'alice@acme.com' }], temat: 'Cześć z Node.js', body: '

Wysłano przez API Unipile!

'
}); konsola.log(wynik); // { tracking_id: 'msg_...' }
Konfiguracja

Wymagania wstępne i konfiguracja

Zanim będziesz mógł użyć przepływu pracy JavaScript API wysyłania wiadomości e-mail w produkcji, potrzebujesz czterech rzeczy: obsługiwanej wersji Node.js, pakietu SDK Unipile, klucza API i punktu końcowego DSN.

Node.js 18+ (zalecane 20)
SDK Unipile używa natywnych fetch i najwyższego poziomu czekać. Node 20 LTS jest zalecany do produkcji. Sprawdź swoją wersję za pomocą node -v.
Klucz API Unipile i DSN
Zaloguj się w panelu Unipile, aby uzyskać swój token dostępu i DSN (osobisty punkt końcowy HTTPS, taki jak api4.unipile.com:13444Oba są wymagane do zainicjowania klienta.
ESM czy CommonJS
SDK obsługuje oba. Dla ESM użyj .mjs pliki lub ustaw "typ":"moduł" w package.json. Dla CommonJS, dynamiczne import() działa również – przykłady poniżej.
Połączone konto e-mail
Wysyłasz e-mail przez powiązane konto (Gmail, Outlook lub IMAP). Następna sekcja przeprowadzi Cię przez przepływ OAuth, aby je powiązać. Robisz to tylko raz dla każdego konta.
Instalacja SDK Unipile
npm
włókno
pnpm
npm install unipile-node-sdk
yarn dodaj unipile-node-sdk
pnpm zainstaluj unipile-node-sdk
.env
# Poświadczenia Unipile (nigdy nie dodawaj tego pliku do repozytorium) UNIPILE_DSN=https://api4.unipile.com:13444 UNIPILE_TOKEN=twój_token_dostępu_tutaj # Identyfikator konta powiązanego konta e-mail ID_KONTA_EMAIL=acc_xxxxxxxxxxxxxxxx

Dodaj .env do twojego .gitignore. Użyj dotenv lub natywny Node 20.6+ --plik-środowiskowy flaga do załadowania go: node --env-file=.env wyślij.mjs.

Łączenie kont

Konfiguracja pierwszego konta e-mail

The ujednolicone API pocztowe używa jednego account_id aby abstrakcyjnie obsłużyć różnice między dostawcami. Połącz konto raz, a następnie wywołaj client.email.send() identycznie u wszystkich trzech dostawców.

Wybierz swojego dostawcę poniżej, aby zobaczyć dokładny fragment kodu Node.js. Zwrócone `account_id` jest tym, co przechowujesz i ponownie wykorzystujesz przy każdym kolejnym wysłaniu.

GmailGmail OAuth
PerspektywyOutlook / Microsoft 365
IMAPSMTP / IMAP
connect-gmail.mjs
import { UnipileClient } z 'unipile-node-sdk'; const klient = nowy UnipileClient(process.env.UNIPILE_DSN, process.env.UNIPILE_TOKEN); // Krok 1: wygeneruj hostowany link OAuth dla Gmaila const { url } = await konta klienta.utwórzPołączenieAutoryzacyjne({ typ: 'GOOGLE', success_redirect_url: process.env.OAUTH_CALLBACK_URL, failure_redirect_url: process.env.OAUTH_CALLBACK_URL + '?error=1', }); // Krok 2: przekieruj użytkownika na `url` konsola.log('Przekieruj użytkownika do:', adres URL); // Krok 3: Unipile wysyła POST z account_id do Twojego callbacku // Zapisz: process.env.EMAIL_ACCOUNT_ID = result.account_id
connect-outlook.mjs
import { UnipileClient } z 'unipile-node-sdk'; const klient = nowy UnipileClient(process.env.UNIPILE_DSN, process.env.UNIPILE_TOKEN); // Działa dla poczty Outlook osobistej ORAZ Microsoft 365 / Exchange Online const { url } = await konta klienta.utwórzPołączenieAutoryzacyjne({ typ: 'MICROSOFT', success_redirect_url: process.env.OAUTH_CALLBACK_URL, failure_redirect_url: process.env.OAUTH_CALLBACK_URL + '?error=1', }); // Przekieruj użytkownika -> dokończy przepływ Microsoft OAuth konsola.log('Przekieruj użytkownika do:', adres URL); // Zobacz: /syncing-emails-with-microsoft-graph-api-a-developers-guide/
connect-imap.mjs
import { UnipileClient } z 'unipile-node-sdk'; const klient = nowy UnipileClient(process.env.UNIPILE_DSN, process.env.UNIPILE_TOKEN); // SMTP/IMAP: podaj dane uwierzytelniające bezpośrednio (bez przekierowania OAuth) const konto = await konta klienta.create({ typ: 'IMAP', imap: { username: process.env.IMAP_UŻYTKOWNIK, hasło: process.env.HASŁO_IMAP, host: process.env.HOST_IMAP, port: 993, }, smtp: { username: process.env.IMAP_UŻYTKOWNIK, hasło: process.env.HASŁO_IMAP, host: process.env.SMTP_HOST, port: 587, }, }); konsola.log(account.account_id); // przechować to
Gmail Gmail
Korzysta z protokołu Google OAuth 2.0. Nie są potrzebne hasła aplikacji. Zobacz pełny Tutorial dotyczący wysyłania wiadomości e-mail za pomocą interfejsu API Gmail do konfiguracji zakresów i ekranu zgody.
Perspektywy Outlook / Microsoft 365
Używa Microsoft Graph OAuth. Obejmuje to osobisty program Outlook i dzierżawy M365. Szczegóły w Przewodnik po wiadomościach e-mail programu Microsoft Graph.
IMAP SMTP / IMAP
Działa z każdym dostawcą udostępniającym IMAP/SMTP (Yahoo, ProtonMail Bridge, niestandardowe serwery pocztowe). Przeczytaj Przewodnik po rozwiązaniu API IMAP.
Rdzeń API

Wysyłanie pierwszego e-maila z Node.js

Trzy gotowe do produkcji wzorce dla przepływu pracy API wysyłania wiadomości e-mail w języku JavaScript: zwykły tekst, HTML z DW/UDW i odczytywanie obiektu odpowiedzi. Wszystkie używają tych samych client.email.send() zadzwoń.

1
E-mail w czystym tekście
Najprostszy przypadek
plain-text.mjs
import { UnipileClient } z 'unipile-node-sdk'; const klient = nowy UnipileClient(process.env.UNIPILE_DSN, process.env.UNIPILE_TOKEN); const wynik = await client.email.wysyłać({ account_id: process.env.ID_KONTA_EMAIL, do: [{ display_name: 'Bob', identyfikator: 'bob@example.com' }], temat: 'Witamy na platformie', body: 'Cześć Bob, twoje konto jest gotowe.', }); konsola.log(wynik.identyfikator_śledzenia); // msg_xxxxxxxxxxxxxxxx
202 Zaakceptowano - tracking_id uzupełnione
2
HTML body z CC i DW
Wielu odbiorców
html-cc-bcc.mjs
const wynik = await client.email.wysyłać({ account_id: process.env.ID_KONTA_EMAIL, do: [{ display_name: 'Alicja', identyfikator: 'alice@acme.com' }], cc: [{ imię_wyświetlane: 'Kierownik', identyfikator: 'boss@acme.com' }], dw: [{ imię_wyświetlane: 'Audyt', identyfikator: 'audit@internal.io' }], temat: 'Twoja faktura #1042', // Treść HTML - dostawca renderuje ją natywnie body: `

Faktura #1042

Kwota do zapłaty: $299

Zapłać teraz `
, }); konsola.log('Wysłano:', result.tracking_id);
3
Odwołanie pełnego pola
Wszystkie obsługiwane parametry
PoleTypWymaganyOpis
account_idłańcuchWymaganyIdentyfikator konta e-mail, z którego pochodzi wysyłka
doOdbiorcy[]WymaganyTablica {nazwa_wyświetlana, identyfikator} przedmioty
podmiotłańcuchWymaganyTemat wiadomości e-mail
ciałołańcuchWymaganyTekst zwykły czy ciąg znaków HTML
ccOdbiorcy[]OpcjonalnieDW: dwu-krotne kopiowanie
Dw. kopiaOdbiorcy[]OpcjonalnieDwóch odbiorców kopii ukrytej
zOdbiorcaOpcjonalniePrzesłoń nazwę wyświetlaną nadawcy
reply_tołańcuchOpcjonalnieIdentyfikator wiadomości dostawcy do odpowiedzi (wątki)
załącznikiTablicaOpcjonalnieTablica [nazwa_pliku, Bufor] krotki
nagłówki niestandardoweobiekt[]OpcjonalnieNiestandardowa tablica nagłówków X
opcje_śledzeniaobiektOpcjonalnie{otwiera, linkuje, etykieta} - włącz śledzenie otwarć/kliknięć
Darmowe na start
Gotowi do wysłania e-maila za pomocą API w JavaScript?

Pobierz swój klucz API, połącz konto Gmail lub Outlook w ciągu kilku minut i uruchom przykłady Node.js z tego przewodnika na rzeczywistych skrzynkach pocztowych.

Załączniki

Wysyłanie załączników w Node.js

The załączniki pole akceptuje tablicę [nazwa_pliku, Bufor] krotki. Odczytaj plik za pomocą Node's fs.readFileSync lub przesyłaj strumieniowo z fs.promises.readFile.

Pojedynczy plik z dysku
Użycie fs.promises.readFile(ścieżka) aby uzyskać Bufor, następnie podaj ['nazwa_pliku.pdf', bufor]. Działa dla PDF, DOCX, obrazów, każdego formatu binarnego.
Wiele załączników
Przekaż tablicę krotek. Każda krotka jest niezależna - dowolnie mieszaj typy plików. Brak sztywnego limitu na załącznik, ale zachowaj całkowity ładunek poniżej limitu swojego planu.
Obrazki w tekście (CID)
Osadź obrazy w treści HTML za pomocą cid: schemat. Odwołaj się do tej samej nazwy pliku użytej w krotce załączników: <img src="cid:logo.png">.
Bufor ze strumienia
Generowanie PDF w locie (np. za pomocą pdfkit), zbierz go do Bufora i dołącz bez zapisywania na dysku. Bezpieczne w produkcji dla środowisk bezserwerowych.
attach-file.mjs
import { UnipileClient } z 'unipile-node-sdk'; import obietnice jako fs z 'node:fs'; const klient = nowy UnipileClient(process.env.UNIPILE_DSN, process.env.UNIPILE_TOKEN); // Odczytaj plik do bufora const buforPDF = await fs.odczytajPlik('./faktura.pdf'); czekać client.email.wysyłać({ account_id: process.env.ID_KONTA_EMAIL, to: [{ display_name: 'Klient', identyfikator: 'client@example.com' }], temat: 'Twoja faktura znajduje się w załączniku', body: '

Proszę znaleźć swoją fakturę w załączniku.

'
, załączniki: [ ['faktura.pdf', pdfBufor], // [nazwa_pliku, Bufor] ], });
attach-multiple-inline.mjs
const [logo, raport] = await Obietnica.wszystkofs.odczytajPlik('/logo.png'), fs.odczytajPlik('./raport.xlsx'), ]); czekać client.email.wysyłać({ account_id: process.env.ID_KONTA_EMAIL, do: [{ display_name: 'Zespół', identyfikator: 'team@acme.com' }], temat: 'Raport Q1', body: Logo

Raport Q1

Szczegóły znajdują się w załączonym arkuszu kalkulacyjnym.

`
, załączniki: [ ['logo.png', logo], // wbudowane przez cid:logo.png w treści ['raport.xlsx', raport], // zwykłe załącznik ], });
Limit rozmiaru: Zachowaj indywidualne załączniki poniżej 25 MB (zasadniczy limit Gmaila). W przypadku dużych plików prześlij je do magazynu w chmurze i zamiast tego umieść link do pobrania w treści wiadomości e-mail.
Zaawansowany

Odpowiedzi, Wątki i Śledzenie

Wyjdź poza proste wysyłanie: odpowiedzi na wątki, niestandardowe nagłówki dla idempotencji, śledzenie otwarć/kliknięć za pomocą webhooków oraz Wysyłanie wiadomości e-mail w imieniu użytkownika.

1
Odpowiadanie na wątek

Przekaż identyfikator wiadomości dostawcy (zwrócony w oryginalnej odpowiedzi wysyłania lub z listy wiadomości e-mail) jako reply_to. Unipile wstrzykuje prawidłowy Odpowiedź-Do oraz Bibliografia nagłówki, dzięki czemu wątki odpowiedzi prawidłowo wyświetlają się w Gmailu, Outlooku i klientach IMAP.

reply-thread.mjs
czekać client.email.wysyłać({ account_id: process.env.ID_KONTA_EMAIL, do: [{ display_name: 'Alicja', identyfikator: 'alice@acme.com' }], temat: 'Re: Twoje pytanie', body: '

Dziękuję za kontakt! Oto odpowiedź...

'
, // Id wiadomości dostawcy z oryginalnego e-maila odpowiedz_do: 'msg_xxxxxxxxxxxxxxxx', });
2
Niestandardowe nagłówki i idempotencja

Użycie nagłówki niestandardowe dodać jakikolwiek X- nagłówek. Powszechnym wzorcem jest Klucz-Idempotencji-X aby zapobiec powielaniu wysyłek po ponowieniu próby po przekroczeniu limitu czasu sieci.

nagłówki-niestandardowe.mjs
import { losowyIdentyfikatorUUID } z 'node:crypto'; czekać client.email.wysyłać({ account_id: process.env.ID_KONTA_EMAIL, do: [{ display_name: 'Bob', identyfikator: 'bob@example.com' }], temat: 'Potwierdzenie zamówienia #9981', body: '

Twoje zamówienie zostało potwierdzone.

'
, niestandardowe_nagłówki: [ { nazwa: 'Klucz-Idempotencji-X', wartość: randomUUID}, { nazwa: 'X-Identyfikator Zamówienia', wartość: '9981' }, ], });
3
Śledzenie otwarć i kliknięć za pomocą webhooków

Włącz śledzenie w opcje_śledzenia. Unipile wysyła zdarzenie webhook (e-mail.otwarty / email.kliknięto_link) do zarejestrowanego adresu URL webhooku z etykieta Ustawiasz tutaj, aby móc powiązać zdarzenia z wewnętrznymi identyfikatorami.

tracking.mjs
czekać client.email.wysyłać({ account_id: process.env.ID_KONTA_EMAIL, do: [{ display_name: 'Ołów', identyfikator: 'lead@prospect.com' }], temat: 'Następstwo po Pana/Pani okresie próbnym', body: '

Cześć, chciałem się odezwać...

'
, tracking_options: { opens: true, // uruchamia webhooka email.opened połączenia true, // wyzwala webhook email.link_clicked etykieta: 'crm_lead_12345', // Twój wewnętrzny identyfikator korelacji }, });
4
Wysłano w imieniu innego użytkownika

Podczas tworzenia aplikacji SaaS wielodostępnych każdy użytkownik końcowy łączy swoje konto e-mail. Przechowuj dane account_id na użytkownika w Twojej bazie danych i przekazać go w czasie wysyłki. Zobacz pełny przewodnik po jak wysłać e-mail w imieniu użytkownika.

w imieniu.mjs
// Każdy użytkownik ma swój własny powiązany account_id przechowywany w Twojej bazie danych async function wyslijJakoUzytkownik(userId, do, temat, treść) { const użytkownik = await baza danych.PobierzUżytkownika(userId); return client.email.wysyłać({ account_id: user.unipile_account_id, // na użytkownika to, temat, treść, }); } // Email wysłany z Gmaila Alice, a nie z adresu Twojego serwera czekać wyslijJakoUzytkownik('uzytkownik_alice', odbiorcy, temat, treść);

Pracujesz w Pythonie? Zobacz nasze Implementacja w Pythonie przewodnik.

Gotowe do produkcji

Obsługa błędów i ponawianie prób

Awarie sieci i limity szybkości są nieuniknione na dużą skalę. Oto produkcyjny wzorzec async/await dla Twojej implementacji JavaScriptowego API wysyłania wiadomości e-mail – z wykładniczym wycofywaniem i strukturalnym logowaniem przy użyciu Winston lub Pino.

202
Przyjęte
E-mail został pomyślnie dodany do kolejki. identyfikator_śledzenia jest wypełniony. Nie ma potrzeby ponawiania.
429
Przekroczono limit żądań
Zbyt wiele żądań. Uszanuj Ponów-Po nagłówek. Użyj wykładniczego wycofywania.
401
Nieautoryzowany
Nieprawidłowy lub wygasły token. Sprawdź UNIPILE_TOKEN zmienna środowiskowa. Nie ponawiaj próby - popraw dane uwierzytelniające.
422
Błąd walidacji
Brak wymaganego pola lub nieprawidłowy odbiorca. Sprawdź treść błędu - określa ona, które pole zawiodło.
503
Usługa niedostępna
Przejściowy błąd serwera. Bezpieczne ponowienie próby z opóźnieniem. Sprawdź status.unipile.com w poszukiwaniu incydentów.
404
Konto nie znalezione
The account_id nie istnieje lub został unieważniony. Ponownie połącz konto.
Eksponencjalne wycofywanie z async/await
wyślij-z-ponowieniem.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.

'
, });
Bezpieczeństwo

Najlepsze praktyki bezpieczeństwa w Node.js

Twój UNIPILE_TOKEN udziela pełnego dostępu API. Nigdy nie ujawniaj go po stronie klienta. Zobacz pełny Przewodnik po zabezpieczaniu API poczty elektronicznej do zaawansowanych tematów, w tym DKIM, SPF i rotacji tokenów OAuth.

Nigdy nie ujawniaj kluczy po stronie klienta
Twój UNIPILE_TOKEN musi pozostać na serwerze. Żaden kod JavaScript po stronie przeglądarki - w tym komponenty klienckie Next.js, frontend React ani Vite - NIE MOŻE importować tokenu bezpośrednio.
Użyj trasy proxy backendu
W Next.js utwórz trasę API/api/wyślij-e-mail. W Express, endpoint POST. Najpierw uwierzytelnij własnych użytkowników, a następnie wywołaj serwer Unipile z tokenem z env.
Tokeny odświeżające OAuth
Unipile automatycznie zarządza odświeżaniem tokenów OAuth dla Gmail i Outlook. Twoje zapisane account_id pozostaje ważny. Nie musisz samodzielnie obsługiwać wygasania tokenu dostępu.
DKIM i SPF (reputacja nadawcy)
E-maile wysyłane przez połączone konta Gmail/Outlook dziedziczą podpisy DKIM tych dostawców. W przypadku kont IMAP/SMTP skonfiguruj DKIM na swoim serwerze pocztowym przed połączeniem.
Zweryfikuj dane odbiorcy
Jeśli odbiorcy pochodzą z danych wprowadzonych przez użytkownika, zweryfikuj format adresu e-mail po stronie serwera przed wywołaniem interfejsu API. Interfejs API odrzuci niepoprawnie sformatowane adresy odpowiedzią 422, ale walidacja przed wywołaniem zapewnia bardziej przejrzyste błędy interfejsu użytkownika.
Ogranicz tokeny API według środowiska
Używaj oddzielnych projektów Unipile (i tokenów) dla środowisk deweloperskiego, przejściowego i produkcyjnego. Zapobiega to wysyłaniu e-maili testowych do prawdziwych użytkowników i ogranicza zakres potencjalnego wycieku klucza.
ŹLE Token w kodzie frontendowym
// client.js - NIGDY nie rób tego const klient = nowy UnipileClient( 'https://api4.unipile.com:13444', 'sk_live_xxxxxxxxxx' Ujawniono! );
POPRAWNY Trasa proxy backendu (Next.js)
// app/api/send-email/route.js eksportuj asynchroniczną funkcję POST(req) { // najpierw sprawdź autoryzację const session = czekać getServerSession(); if (!session) return new Response(null,{status:401}); const client = new UnipileClient( process.env.UNIPILE_DSN, // tylko na serwerze process.env.UNIPILE_TOKEN // tylko na serwerze ); czekać client.email.send({...}); }
Przeczytaj cały przewodnik po bezpieczeństwie interfejsu API poczty elektronicznej
Powszechne pułapki

Powszechne pułapki (specyficzne dla Node.js)

Oto najczęstsze błędy popełniane przez programistów podczas pierwszej integracji API do wysyłania e-maili w JavaScript. Każdy z nich jest łatwy do uniknięcia, gdy znasz schemat – i wszystkie mają zastosowanie równie dobrze w kontekście API do wysyłania e-maili w Node.js.

1
Zapominanie o `await` najwyższego poziomu (CommonJS vs ESM)
Najwyższy poziom czekać działa tylko w modułach ES (.mjs lub "typ":"moduł"). W CommonJS, umieść wywołanie send w asynchroniczny IIFE lub użyj .then(). SDK działa w obu przypadkach – wystarczy wybrać odpowiedni format modułu.
cjs-workaround.cjs
// CommonJS: opakuj w asynchroniczną IIFE (asynchronicznie () => { const { UnipileClient } = await import('unipile-node-sdk'); const klient = nowy UnipileClient(process.env.UNIPILE_DSN, process.env.UNIPILE_TOKEN); czekać client.email.wysyłać({ /* ... */ }); })();
2
Używanie Promise.all do masowych wysyłek bez uwzględniania ograniczeń szybkości
Odstrzał 1000 Obietnica.wszystko wysyłane jednocześnie uderzą w limity i spowodują błędy 429. Użyj limitera współbieżności, takiego jak p-ograniczenie aby ograniczyć równoległe żądania.
wysyłka_masowa.mjs
import pLimit z 'p-limit'; const limit = pLimit(5); // maks. 5 jednoczesnych wysyłek const wyniki = await Obietnica.wszystkoodbiorcy.mapa(r => limit(() => client.email.wysyłać({ account_id: proces.env.ID_KONTA_EMAIL, do: [r], temat, treść, }))) );
3
Niepoprawne kodowanie bufora dla załączników
Przekazuj zawsze surowe Bufor obiekt - nie ciąg znaków base64, nie ciąg znaków UTF-8. Jeśli masz zawartość w formacie base64 (np. z webhooka lub odpowiedzi API), najpierw ją przekonwertuj: Buffer.from(base64str, 'base64').
bufor-kodowanie.mjs
// BŁĄD: przekazywanie ciągu znaków załączniki: [['plik.pdf', 'JVBERi0xLjQ...']] // ciąg znaków base64 - błędy! // POPRAWNIE: Obiekt bufora załączniki: [['plik.pdf', Bufor.z(ciąg_base64, 'base64')]] // lub z dysku: załączniki: [['plik.pdf', czekać fs.odczytajPlik('./plik.pdf')]]
4
Nieobsługiwane odrzucenia obietnic kończące działanie procesu
W Node.js, nieobsłużone odrzucenie w scenariuszu "fire-and-forget" wysłać Wywołanie to spowoduje awarię procesu w Node 15+. Zawsze czekać wynik lub dołączyć .catch() Obsługa.
nieobsłużone-odrzucenie.mjs
// BŁĘDNIE: fire-and-forget - powoduje błąd w Node 15+ client.email.wysyłać(ładunek); // bez await, bez .catch() // POPRAWNIE: zawsze obsługuj obietnicę czekać client.email.wysyłać(ładunek) // opcja 1: await .połów(błąd => rejestrator.błąd(err)); // opcja 2: .catch()
5
Bezpośrednie użycie tego API w przeglądarce JavaScript
SDK Unipile i Twój UNIPILE_TOKEN są przeznaczone tylko dla Node.js po stronie serwera. Bezpośrednie wywołanie API przez przeglądarkę ujawni Twój token. Użyj trasy backendowej (trasy API Next.js, punktu końcowego Express, funkcji Netlify/Vercel) jako proxy.
6
Wysyłanie bez połączonego konta (brak account_id)
Nie można wysyłać z adresu ogólnego - każde wysłanie musi odwoływać się do poprawnego account_id Z wcześniej połączonego konta Gmail, Outlook lub IMAP. Interfejs API zwraca kod 404, jeśli identyfikator konta jest nieprawidłowy lub został odłączony.

Często zadawane pytania

Najczęściej zadawane pytania dotyczące wysyłania e-maili w JavaScript i Node.js za pomocą ujednoliconego API e-mail Unipile.

Użyj ujednoliconego API poczty e-mail Unipile zamiast bezpośredniego połączenia SMTP. Zainstaluj unipile-node-sdk, inicjalizuj UnipileClient za pomocą Twojego DSN i tokenu połącz konto Gmail lub Outlook przez OAuth, a następnie wywołaj client.email.send(). Żaden serwer SMTP, żaden port 587, żadna konfiguracja TLS nie jest wymagana z Twojej strony - Unipile zajmuje się warstwą transportową.

Nie - i nie powinieneś. Wywoływanie API Unipile z poziomu JavaScript w przeglądarce naraziłoby twoje UNIPILE_TOKEN do każdego użytkownika, który otworzy Narzędzia deweloperskie. Zawsze wywołuj interfejs API z kontekstu serwera Node.js: trasy Express, trasy API Next.js (app/api/), Vercel Edge Function lub Netlify Function.

Twój frontend wysyła żądanie do własnego punktu końcowego backendu, który uwierzytelnia sesję użytkownika, a następnie wywołuje serwer Unipile.

Nodemailer łączy się bezpośrednio z serwerem SMTP z Twojego procesu Node.js. Wymaga od Ciebie zarządzania poświadczeniami SMTP, obsługi TLS, samodzielnej konfiguracji DKIM oraz osobnego radzenia sobie z niedoskonałościami każdego dostawcy.

API pocztowe Unipile to warstwa abstrakcji w chmurze: łączysz konta przez OAuth (nie są potrzebne dane uwierzytelniające SMTP dla Gmail/Outlook), otrzymujesz jeden spójny pakiet SDK dla wszystkich dostawców, a Unipile zajmuje się transportem, ponawianiem prób i odświeżaniem tokenów. Kompromisem jest to, że Twoje wysyłki przechodzą przez infrastrukturę Unipile, a nie bezpośrednie połączenie SMTP.

Tak. Ten unipile-node-sdk paczka zawiera definicje typów TypeScript. Otrzymujesz pełne autouzupełnianie i bezpieczeństwo typów dla wysłać ładunek, w tym Odbiorca, opcje_śledzenia, i typ odpowiedzi.

import { UnipileClient } z 'unipile-node-sdk'; // Pełne typy TS – autouzupełnianie działa w VSCode const klient: UnipileClient = nowy UnipileClient(dsn, token); const wynik = await client.email.wysyłać({ /* wpisano! */ });

W przypadku wysyłek o dużej wolumenie użyj ograniczania współbieżności (np. p-ograniczenie z 5-10 jednoczesnymi połączeniami), dodaj wykładnicze opóźnienie dla odpowiedzi 429 i rozłóż wysyłkę na wiele połączonych kont, jeśli to możliwe. Każde połączone konto e-mail ma własne limity wysyłki określone przez dostawcę (Gmail: ~500/dzień dla zwykłych kont, więcej dla Workspace).

Dla prawdziwego masowego/marketingowego wysyłania e-maili na dużą skalę (miliony odbiorców), rozważ dedykowany ESP (Mailgun, SendGrid) obok Unipile do wysyłek transakcyjnych i opartych na OAuth.

Następny.js: Użyj tras API (app/api/wyslij-email/trasa.js) lub Akcje po stronie serwera. Zachowaj tworzenie instancji SDK tylko po stronie serwera.

Nuxt użyj tras serwerowychserwer/api/send-email.post.ts). SDK jest dostępny tylko dla Node.js, więc nie może trafić do composable lub wtyczki, która działa po stronie klienta.

NestJS: stwórz ModułEmail z usługą, która opakowuje UnipileClient. Wstrzyknij to wszędzie tam, gdzie potrzebujesz wyzwalać wysyłki – w kontrolerach, zadaniach CRON lub programach obsługi zdarzeń.

Masz jeszcze jakieś pytania? Nasz zespół służy pomocą.

pl_PLPL