JavaScript ile API Üzerinden E-posta Gönderme (Node.js Eğitim Rehberi)

İçindekiler
İçindekiler 14 bölüm
Başlarken
E-posta Gönderme
Üretim
Referans
JavaScript Eğitimi

Nasıl API Üzerinden E-posta Gönder JavaScript (Node.js Eğitimleri)

SMTP baş döndürücülerini atlayın. Bu kılavuz, Node.js'de e-posta göndermeyi nasıl yapacağınızı gösterir Unipile birleştirilmiş e-posta API'si - Gmail, Outlook ve SMTP için 10 satırın altında JavaScript koduyla kopyala-yapıştır.

e-posta gönder API'si javascript Node.js e-posta gönderme API'si Gmail / Outlook / SMTP ESM + async/await
sendEmail.mjs
İthalat { UnipileClient } itibaren 'unipile-node-sdk'; const müşteri = yeni UnipileClientprocess.env.UNIPILE_DSN, process.env.UNIPILE_TOKEN ); bekliyor client.email.gönder({ account_id: 'HESAP_KODUNUZ', kime: [{ görüntülenme_adı: 'Alice', tanımlayıcı: 'alice@example.com' }], konu: 'Node.js'den Merhaba', body: '

Unipile ile Gönderildi!

'
});
E-posta teslim edildi - 202 Kabul edildi
Şunlarla çalışır: Gmail Görünüm IMAP
Özetle

2. Satır Node.js Örneği

Zaten ne olduğunu biliyorsanız E-posta Gönderme API'si ve çalışan bir e-posta API JavaScript kodu göndermek istiyorum, işte burada. Tam eğitim aşağıdadır.

1
SDK'yı yükleyin
npm install unipile-node-sdk
2
Ortam değişkenlerini ayarla
Ekle UNIPILE_DSN ve UNIPILE_TOKEN sana .env dosya.
3
Bir e-posta hesabı bağla
Gmail/Outlook için OAuth veya herhangi bir IMAP sunucusu için SMTP kimlik bilgileri - tek API çağrısı.
4
Ara client.email.gönder()
Geç account_id, için, konuve vücut. Tamamlandı.
Aynı kod Gmail, Outlook ve herhangi bir IMAP sunucusu için çalışır - sağlayıcıya özel mantık gerekmez. Kontrol edin E-posta API rehberi tam kavramsal bakış için.
gönder.mjs
İthalat { UnipileClient } itibaren 'unipile-node-sdk'; const müşteri = yeni UnipileClientprocess.env.UNIPILE_DSN, process.env.UNIPILE_TOKEN ); const sonuç = bekle client.email.gönder({ account_id: 'acc_xxxxxxxxxxxxxxxx', kime: [{ görünen_ad: 'Alice Martin', tanımlayıcı: 'alice@acme.com' }], konu: 'Node.js'den Merhaba', body: '

Unipile API Üzerinden Gönderildi!

'
}); konsol.log(sonuç); // { takip_kimliği: 'msg_...' }
Kurulum

Önkoşullar ve Kurulum

Üretimde e-posta gönderme API JavaScript iş akışını kullanabilmeniz için dört şeye ihtiyacınız var: desteklenen bir Node.js sürümü, Unipile SDK'sı, bir API anahtarı ve bir DSN uç noktası.

Node.js 18+ (20 önerilir)
Unipile SDK yerel olarak kullanır fetch ve üst düzey bekliyor. Prodüksiyon için Node 20 LTS önerilir. Sürümünüzü kontrol etmek için node -v.
Unipile API Anahtarı ve DSN
Erişim jetonunuzu ve DSN'yi (kişisel bir HTTPS uç noktası gibi) almak için Unipile kontrol paneline kaydolun api4.unipile.com:13444Her ikisi de istemciyi başlatmak için gereklidir.
ESM veya CommonJS
SDK'nın her ikisi de desteği vardır. ESM için, şunu kullanın .mjs dosyalar veya ayarla "tipi: "modül" içinde package.json. OrtakJS için, dinamik içe aktar() Ayrıca çalışır - örnekler aşağıdadır.
Bağlı bir e-posta hesabı
E-posta gönderiyorsun aracılığıyla bağlı bir hesap (Gmail, Outlook veya IMAP). Bir sonrakı bölüm, birini bağlamak için OAuth akışında size yol gösterir. Bunu hesap başına yalnızca bir kez yaparsınız.
Unipile SDK'yı Kurma
npm
iplik
PNPM
npm install unipile-node-sdk
unipile-node-sdk ekle
pnpm add unipile-node-sdk
.env
# Unipile kimlik bilgileri (bu dosyayı asla kaydetmeyin) UNIPILE_DSN=https://api4.unipile.com:13444 UNIPILE_TOKEN=buraya_erişim_tokenin # Bağlı e-posta hesabının hesap kimliği EPOSTA_HESAP_KODU=acc_xxxxxxxxxxxxxxxx

Ekle .env sana .gitignore. Kullan dotenv veya yerel Node 20.6+ --env-dosyası yüklemek için bayrak: node --env-file=.env gönder.mjs.

Hesap Bağlama

İlk E-posta Hesabınızı Bağlama

Bu birleşik e-posta API'si tek bir kullanır account_id sağlayıcı farklılıklarını soyutlamak için. Bir hesabı bir kez bağlayın, sonra çağırın client.email.gönder() üç sağlayıcıda da aynı şekilde.

Aşağıdan sağlayıcınızı seçerek tam Node.js kod parçacığını görüntüleyin. Döndürülen account_id, saklayacağınız ve sonraki her gönderim için yeniden kullanacağınız bilgidir.

GmailGmail OAuth
GörünümOutlook / Microsoft 365
IMAPSMTP / IMAP
connect-gmail.mjs
İthalat { UnipileClient } itibaren 'unipile-node-sdk'; const müşteri = yeni UnipileClient(işlem.ortamı.UNIPILE_DSN, process.env.UNIPILE_TOKEN); // Adım 1: Gmail için barındırılan bir OAuth bağlantısı oluşturun const { URL } = bekle müşteri.hesap.HostedAuthLinkOluştur({ type: 'Google', success_redirect_url: process.env.OAUTH_CALLBACK_URL, failure_redirect_url: process.env.OAUTH_CALLBACK_URL + '?hata=1', }); // Adım 2: kullanıcıyı `url`'ye yönlendirin konsol.log('Kullanıcıyı şuraya yönlendir:', ", url); // Adım 3: Unipile, account_id'yi geri aramanıza POST eder // Sakla: process.env.EMAIL_ACCOUNT_ID = result.account_id
connect-outlook.mjs
İthalat { UnipileClient } itibaren 'unipile-node-sdk'; const müşteri = yeni UnipileClient(işlem.ortamı.UNIPILE_DSN, process.env.UNIPILE_TOKEN); // Hem kişisel Outlook hem de Microsoft 365 / Exchange Online için çalışır const { URL } = bekle müşteri.hesap.HostedAuthLinkOluştur({ type: 'MİCROSOFT', success_redirect_url: process.env.OAUTH_CALLBACK_URL, failure_redirect_url: process.env.OAUTH_CALLBACK_URL + '?hata=1', }); // Kullanıcıyı yönlendir -> Microsoft OAuth akışını tamamlarlar konsol.log('Kullanıcıyı şuraya yönlendir:', ", url); // Bkz: /microsoft-graph-api-ile-e-posta-senkronizasyonu-bir-penguen-rehberi/
connect-imap.mjs
İthalat { UnipileClient } itibaren 'unipile-node-sdk'; const müşteri = yeni UnipileClient(işlem.ortamı.UNIPILE_DSN, process.env.UNIPILE_TOKEN); // SMTP/IMAP: kimlik bilgilerini doğrudan ilet (OAuth yönlendirmesi yok) const hesap = bekle müşteri.hesap.create({ type: 'IMAP', imap: { kullaniciAdi: process.env.IMAP_KULLANICI, şifre: process.env.IMAP_SIFRE, host: process.env.IMAP_SUNUCUSU, bağlantı noktası: 993, }, smtp: { kullanıcı_adı: process.env.IMAP_KULLANICI, şifre: process.env.IMAP_SIFRE, host: process.env.SMTP_SUNUCU, bağlantı noktası: 587, }, }); konsol.log(hesap.hesap_id); // bunu sakla
Gmail Gmail
Google OAuth 2.0 kullanır. Uygulama şifrelerine gerek yoktur. Tamamını görün Gmail API e-posta gönderme eğitim rehberi Kapsamlar ve onay ekranı kurulumu için.
Görünüm Outlook / Microsoft 365
Microsoft Graph OAuth kullanır. Kişisel Outlook ve M365 kiracılarını kapsar. Ayrıntılar aşağıdadır Microsoft Graph e-posta kılavuzu.
IMAP SMTP / IMAP
IMAP/SMTP'yi (Yahoo, ProtonMail Bridge, özel posta sunucuları) sunan herhangi bir sağlayıcıyla çalışır. IMAP API çözüm rehberi.
Çekirdek API

Node.js'ten İlk E-postanızı Gönderme

E-posta gönderme API JavaScript iş akışı için üretim ortamına hazır üç desen: düz metin, HTML CC/BCC ile ve yanıt nesnesini okuma. Hepsi aynı şeyi kullanır client.email.gönder() ara.

1
Düz metin e-posta
En basit durum
düz-metin.mjs
İthalat { UnipileClient } itibaren 'unipile-node-sdk'; const müşteri = yeni UnipileClient(işlem.ortamı.UNIPILE_DSN, process.env.UNIPILE_TOKEN); const sonuç = bekle client.email.gönder({ account_id: process.env.EPOSTA_HESAP_KODU, kime: [{ görüntülenme_adı: 'Bob', tanımlayıcı: 'bob@example.com' }], konu: 'Platforma hoş geldiniz', body: 'Merhaba Bob, hesabın hazır.', }); konsol.log(result.tracking_id); // mesaj_xxxxxxxxxxxxxxxx
202 Kabul Edildi - result.tracking_id dolduruldu
2
HTML gövdesi, CC ve BCC ile
Çoklu alıcı
html-cc-bcc.mjs
const sonuç = bekle client.email.gönder({ account_id: process.env.EPOSTA_HESAP_KODU, kime: [{ görüntü_adı: 'Alice', tanımlayıcı: 'alice@acme.com' }], cc: [{ görüntü adı: 'Yönetici', tanımlayıcı: 'boss@acme.com' }], gizli_alicilar: [{ gorunen_ad: 'Denetim', tanımlayıcı: 'audit@internal.io' }], konu: 'Faturanız #1042', // HTML body - sağlayıcı bunu yerel olarak oluşturur body: `

Fatura #1042

Ödenecek Tutar: $299

Şimdi öde `
, }); konsol.log('Gönderildi:', result.izleme_kimliği);
3
Tam alan referansı
Desteklenen tüm parametreler
AlanTipGerekliAçıklama
account_iddiziGerekliGönderilecek e-posta hesabının kimliği
içinAlıcı[]GerekliDizisi {görünen_ad, tanımlayıcı} nesneler
konudiziGerekliE-posta konu başlığı
vücutdiziGerekliDüz metin veya HTML dizgisi
ccAlıcı[]İsteğe bağlıBilgi alanlar
gizli kopyaAlıcı[]İsteğe bağlıGizli Kopya Alıcıları
itibarenAlıcıİsteğe bağlıGönderen adını geçersiz kıl
reply_todiziİsteğe bağlıYanıtlanacak sağlayıcı mesaj kimliği (konular)
EKLERDiziİsteğe bağlıDizisi [dosya adı, Tampon] demetler
özel_başlıklarnesne[]İsteğe bağlıÖzel X-başlıklar dizisi
takip_seçeneklerinesneİsteğe bağlı{açılır, bağlar, etiket} - açma/tıklama takibini etkinleştir
Başlangıç için ücretsiz
JavaScript ile API üzerinden e-posta göndermeye hazır mısınız?

API anahtarınızı alın, dakikalar içinde bir Gmail veya Outlook hesabı bağlayın ve bu kılavuzdaki Node.js örneklerini gerçek posta kutularına karşı çalıştırın.

Ekler

Node.js'de Ek Gönderme

Bu EKLER alan bir dizi kabul eder [dosya adı, Tampon] Tuple'lar. Node'un dosyasını oku fs.readFileSync veya oradan izleyin fs.promises.readFile.

Diskten tek dosya
Kullanım fs.promises.readFile(yol) Buffer elde etmek, sonra geçmek dosyaadı.pdf, arabellek. PDF, DOCX, resimler, her türlü ikili dosya için çalışır.
Birden fazla dosya
Tuple dizisi geçirin. Her tuple bağımsızdır - dosya türlerini serbestçe karıştırın. Eke kişi başına sabit bir üst sınır yoktur, ancak toplam yükü planınızın sınırı altında tutun.
Satır içi resimler (CID)
HTML gövdesine resim yerleştirmek için cid: ekler demetindekiyle aynı dosya adına atıfta bulunun: <img src="cid:logo.png">.
Bir akıştan önbellek
Anında PDF oluştur (örneğin, şununla pdfkit), bir Tampon'a toplayın ve diske yazmadan ekleyin. Sunucusuz ortamlar için üretim düzeyinde güvenlidir.
dosya-ekle.mjs
İthalat { UnipileClient } itibaren 'unipile-node-sdk'; İthalat vaatler olarak fs } itibaren 'node:fs'; const müşteri = yeni UnipileClient(işlem.ortamı.UNIPILE_DSN, process.env.UNIPILE_TOKEN); // Dosyayı bir Buffer'a oku const pdfTamponu = bekle fs.dosyayıoku('./fatura.pdf'); bekliyor client.email.gönderhesap_kimliği: process.env.EPOSTA_HESAP_KODU, kime: [{ görüntü_adı: 'Müşteri', tanımlayıcı: 'client@example.com' }], konu: 'Faturanız ektedir', body: '

Faturanız ektedir.

'
, ekler: [ ['fatura.pdf', pdfBuffer], // [dosya adı, Tampon] ], });
ekle-çoklu-satır içi.mjs
const [logo, rapor] = bekle Promise.all([ fs.dosyayıoku('./logo.png'), fs.dosyayıoku('./rapor.xlsx'), ]); bekliyor client.email.gönder({ account_id: process.env.EPOSTA_HESAP_KODU, kime: [{ gönderen_adı: 'Takım', tanımlayıcı: 'team@acme.com' }], konu: 'Ilk Çeyrek Raporu', body: Logo

Q1 Raporu

Ayrıntılar için lütfen ekteki elektronik tabloya bakınız.

`
, ekler: [ ['logo.png', logo], // satır içi cid:logo.png ile gövdede ['rapor.xlsx', rapor], // normal ek ], });
Sınırınız: Tek tek eklerin 25 MB'ı geçmemesini sağlayın (Gmail'in katı sınırı budur). Büyük dosyalar için, bulut depolama alanına yükleyin ve bunun yerine e-posta gövdesine bir indirme bağlantısı ekleyin.
Gelişmiş

Yanıtlar, Konular ve Takip

Temel gönderimlerin ötesine geçin: iş parçacığı yanıtları, değişmezlik için özel üstbilgiler, webhook'lar aracılığıyla açılma/tıklanma izleme ve Bir kullanıcı adına e-posta gönderme.

1
Bir konuya yanıt vermek

Gönderen yanıtında veya e-postaları listeleme yoluyla döndürülen sağlayıcı mesaj kimliğini olarak geçirin reply_to. Unipile doğru olanı enjekte eder Yanıt-Kime ve Referanslar Gmail, Outlook ve IMAP istemcilerinde doğru şekilde yanıt dizisi oluşturmak için başlıklar.

yanıt-konusu.mjs
bekliyor client.email.gönder({ account_id: process.env.EPOSTA_HESAP_KODU, kime: [{ gönderen_adı: 'Alice', tanımlayıcı: 'alice@acme.com' }], konu: 'Y: Sorunuz', body: '

Ulaştığınız için teşekkürler! İşte cevap...

'
, // Orijinal e-postadaki sağlayıcı mesaj kimliği cevapla: 'msg_xxxxxxxxxxxxxxxx', });
2
Özel başlıklar ve stateMutability

Kullanım özel_başlıklar eklemek istediğiniz herhangi bir X- başlık. Yaygın bir desen şudur: X-Idempotency-Anahtarı Ağ zaman aşımından sonra yeniden denerken yinelenen gönderimleri önlemek için.

özel-başlıklar.mjs
İthalat { rastgeleUUID } itibaren 'düğüm:kripto'; bekliyor client.email.gönder({ account_id: process.env.EPOSTA_HESAP_KODU, kime: [{ gönderen_adı: 'Bob', tanımlayıcı: 'bob@example.com' }], konu: 'Sipariş onayı #9981', body: '

Siparişiniz onaylandı.

'
, özel_başlıklar: [ { adı: 'X-Idempotency-Key', değer: rastgeleUUID) }, { name: 'X-Sipariş-ID', değer: '9981' }, ], });
3
Webhook'lar aracılığıyla açılma ve tıklama takibi

Şurada izlemeyi etkinleştir takip_seçenekleri. Unipile bir webhook olayı gönderire-posta.açıldı / email.link_tıklandı) kayıtlı webhook URL'nize etiket Olayları, dahili kimliklerinizle ilişkilendirebilmeniz için buraya ayarlarsınız.

tracking.mjs
bekliyor client.email.gönder({ account_id: process.env.EPOSTA_HESAP_KODU, kime: [{ gönderen_adı: 'Kurşun', tanımlayıcı: 'lead@prospect.com' }], konu: 'Denemenizin ardından', body: '

Merhaba, bilgi almak istedim...

'
, tracking_options: { açılmalar: true, // fires e-posta.açıldı webhook'unu tetikler bağlantılar true, // fires email.link_clicked webhook etiket 'crm_lead_12345', // dahili korelasyon kimliğiniz }, });
4
Başka bir kullanıcı adına gönderiliyor

Çok kiracılı SaaS uygulamaları oluştururken, her son kullanıcı kendi e-posta hesabını bağlar. E-postayı saklayın account_id veritabanınızdaki kullanıcı başına ve gönderme zamanında iletin. Tam kılavuza bakın Bir kullanıcı adına e-posta gönderme.

vekaleten
// Her kullanıcının veritabanınızda saklanan kendi bağlantılı hesap_kimliği vardır async function KullanıcıOlarakGönder(kullanıcıId, kime, konu, içerik) { const kullanıcı = bekle veritabanı.KullanıcıAl(kullanıcıId); return client.email.gönderhesap_kimliği: user.unipile_account_id, // kullanıcı başına alıcı, konu, gövde, }); } // E-posta alice'in Gmail'inden gönderilir, sunucu adresinizden değil bekliyor KullanıcıOlarakGönder('kullanıcı_alice', alıcılar, konu, gövde);

Python'da mı çalışıyorsunuz? Bizimkine bakın Python uygulaması rehber.

Üretime Hazır

Hata Yönetimi ve Yeniden Denemeler

Ağ hataları ve hız sınırları ölçekte kaçınılmazdır. İşte e-posta gönderme API'nizin JavaScript uygulamasında kullanabileceğiniz, üstel geri çekilme ve Winston veya Pino kullanarak yapılandırılmış günlük kaydı içeren, üretim düzeyinde bir async/await deseni.

202
Kabul Edildi
E-posta başarıyla sıraya alındı. takip_kimliği dolduruldu. Yeniden denemeye gerek yok.
429
Sınırlı Oran
Çok fazla istek. Saygı duy Yeniden Dene Sonra Başlık. Üstel geri çekilme kullanın.
401
Yetkisiz
Geçersiz veya süresi dolmuş belirteç. Kontrol edin UNIPILE_TOKEN ortam değişkeni. Tekrar deneme - kimlik bilgilerini düzelt.
422
Doğrulama Hatası
Gerekli alan eksik veya alıcı bozuk. Hata gövdesini kontrol edin - hangi alanın başarısız olduğunu belirtiyor.
503
Hizmet Kullanılamıyor
Geçici sunucu hatası. Geri çekilme ile yeniden denemek güvenlidir. Olaylar için status.unipile.com adresini kontrol edin.
404
Hesap Bulunamadı
Bu account_id mevcut değil veya iptal edilmiş. Hesabı yeniden bağlayın.
Async/await ile üssel geri çekilme
yeniden-dene-ile-gönder.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.

'
, });
Güvenlik

Node.js'te Güvenlik En İyi Uygulamaları

Senin UNIPILE_TOKEN tam API erişimi sağlar. Asla istemci tarafında ifşa etmeyin. Tamamını görün E-posta API Güvenlik Rehberi DKIM, SPF ve OAuth token rotasyonu gibi gelişmiş konular için.

Anahtarları istemci tarafında asla paylaşmayın
Senin UNIPILE_TOKEN sunucuda kalmalıdır. Next.js istemci bileşenleri, React ön ucu veya Vite dahil olmak üzere tarayıcı tarafındaki herhangi bir JavaScript, belirteci doğrudan içe AKTARMAMALIDIR.
Bir arka uç proxy rotası kullanın
Next.js'de bir API rotası oluştur (/api/eposta-gonderExpress'te, bir POST uç noktası. Önce kendi kullanıcılarınızı kimlik doğrulayın, ardından .env'den alınan jetonla Unipile'ı sunucu tarafında çağırın.
OAuth yenileme belirteçleri
Unipile, Gmail ve Outlook OAuth jeton yenilemesini otomatik olarak yönetir. Depoladığınız account_id geçerli kalır. Erişim belirteci süresinin dolmasını kendiniz yönetmeniz gerekmez.
DKIM ve SPF (gönderen itibarı)
Bağlı Gmail/Outlook hesapları aracılığıyla gönderilen e-postalar, bu sağlayıcıların DKIM imzalarını miras alır. IMAP/SMTP hesapları için, bağlamadan önce posta sunucunuzda DKIM'yi yapılandırın.
Alıcı girişini doğrula
Alıcılar kullanıcı girdisinden geliyorsa, API'yi çağırmadan önce e-posta formatını sunucu tarafında doğrulayın. API, bozuk biçimlendirilmiş adresleri 422 ile reddedecektir, ancak çağırmadan önce doğrulama daha temiz kullanıcı deneyimi hataları verir.
Ortama göre API belirteçlerini kapsam dışı bırak
test gönderilerinin gerçek kullanıcılara gitmesini engeller ve bir anahtar sızdırılırsa etki alanını sınırlar.
YANLIŞ Önyüz kodunda jeton
// client.js - ASLA bunu yapma const client = UnipileClient'i başlat 'https://api4.unipile.com:13444', 'sk_live_xxxxxxxxxx' açığa çıktı! );
DOĞRU Arka uç proxy rotası (Next.js)
// app/api/send-email/route.js export async function POST(req) { // önce kimlik doğrulama const session = bekliyor getServerSession(); if (!session) return new Response(null,{status:401}); const client = new UnipileClient( process.env.UNIPILE_DSN, // yalnızca sunucu process.env.UNIPILE_TOKEN // yalnızca sunucu ); bekliyor client.email.gönder({...}); }
E-posta API güvenlik kılavuzunun tamamını okuyun
Yaygın Tuzaklar

Yaygın Hatalar (Node.js'e Özgü)

Bir JavaScript send email API'sini ilk kez entegre ederken geliştiricilerin yaptığı en sık hatalar şunlardır. Her biri, kalıbı bildiğinizde kaçınılması kolaydır - ve hepsi Node.js send email API bağlamına eşit şekilde uygulanır.

1
Üst düzey await'i unutmak (CommonJS vs ESM)
Üst düzey bekliyor yalnızca ES modüllerinde çalışır (.mjs veya "tipi: "modül"). CommonJS'de, gönderim çağrınızı bir ... içine alın Eşzamansız IIFE veya kullan .sonra(). SDK her ikisinde de çalışır - sadece doğru modül formatını seçin.
cjs-workaround.cjs
// CommonJS: async IIFE içine sarın (async () => { const { UnipileClient } = bekle İthalat('unipile-node-sdk'); const müşteri = yeni UnipileClient(işlem.ortamı.UNIPILE_DSN, process.env.UNIPILE_TOKEN); bekliyor client.email.gönder({ /* ... */ }); })();
2
Toplu gönderiler için hız sınırlaması farkındalığı olmadan Promise.all kullanmak
1.000 Ateşleme Promise.all aynı anda gönderme, hız sınırlarına takılacak ve 429 hatalarına neden olacaktır. Bir eşzamanlılık sınırlayıcı kullanın, örneğin p-limit paralel istekleri sınırlamak.
toplu gönderim.mjs
İthalat pSınır itibaren 'p-limit'; const limit pLimit(5); // en fazla 5 eşzamanlı gönderim const Sonuçlar = bekle Promise.allalıcılar.Harita(r => limit(() => client.email.gönderaccount_id: process.env.EPOSTA_HESAP_KODU, kime: [r], konu, gövde, }))) );
3
Ekler için yanlış arabellek kodlaması
Her zaman ham geç Tampon nesne - base64 dizesi değil, UTF-8 dizesi değil. Base64 içeriğiniz varsa (örneğin bir webhook veya API yanıtından), önce dönüştürün: Buffer.from(base64str, 'base64').
tampon kodlama.mjs
// YANLIŞ: string geçiliyor ekler: [['dosya.pdf', 'JVBERi0xLjQ...']] // base64 dizesi - bozuluyor! // DOĞRU: Tampon nesnesi ekler: [['dosya.pdf', Tampon.itibaren(base64str, 'base64')]] // veya diskten: ekler: [['dosya.pdf', bekliyor fs.dosyayıoku('./dosya.pdf')]]
4
İşlenmeyen Promise reddetmeleri işlemi çökertiyor
Node.js'de, ateşle ve unut gönder() Çağrı, Node 15+'ta işlemi her zaman çökertecektir. bekliyor sonuç veya ekle .catch() işleyici.
işlenmemiş-reddetme.mjs
// YANLIŞ: fire-and-forget - Node 15+'ta hatada çöküyor client.email.gönder(yük); // await yok, .catch() yok // DOĞRU: her zaman promise'i ele alın bekliyor client.email.gönder(yük) // seçenek 1: await .yakalamak(hata => kayıtçı.hata(err)); // seçenek 2: .catch()
5
Bu API'yi doğrudan tarayıcı JavaScript'inde kullanmak
Unipile SDK'nız ve sizin UNIPILE_TOKEN sunucu tarafı Node.js içindir. Tarayıcıdan doğrudan API'ye fetch yapmak belirtecinizi açığa çıkaracaktır. Bir vekil sunucu olarak bir arka uç rotası (Next.js API rotası, Express uç noktası, Netlify/Vercel fonksiyonu) kullanın.
6
Bağlı hesap olmadan gönderme (hesap_kimliği eksik)
Genel bir adresten gönderim yapamazsınız - her gönderim geçerli bir adrese atıfta bulunmalıdır account_id Daha önce bağlanmış bir Gmail, Outlook veya IMAP hesabından. API, account_id eksikse veya bağlantısı kesilmişse 404 döndürür.

Sıkça Sorulan Sorular

JavaScript ve Node.js'de Unipile birleşik e-posta API'si ile e-posta gönderme hakkında sık sorulan sorular.

Doğrudan bir SMTP bağlantısı yerine Unipile birleşik e-posta API'sini kullanın. Kurun unipile-node-sdk, başlat UnipileClient DSN'niz ve jetonunuz ile, OAuth üzerinden bir Gmail veya Outlook hesabı bağlayın, ardından çağırın client.email.gönder(). Sizin tarafınızdan SMTP sunucusu, port 587 veya TLS yapılandırmasına gerek yok - Unipile taşıma katmanını yönetir.

Hayır - ve yapmamalısınız. Tarayıcı JavaScript'inden Unipile API'sini çağırmak, API anahtarınızı ortaya çıkaracaktır UNIPILE_TOKEN DevTools'u açan herhangi bir kullanıcıya. API'yi her zaman sunucu taraflı bir Node.js bağlamından çağırın: bir Express rotası, bir Next.js API rotası (app/api/), bir Vercel Kenar Fonksiyonu veya bir Netlify Fonksiyonu.

Ön yüzünüz, kullanıcı oturumunu kimlik doğrulayan ve ardından Unipile sunucusunu çağıran kendi arka uç uç noktanıza bir istek gönderir.

Nodemailer, Node.js işleminizden doğrudan bir SMTP sunucusuna bağlanır. SMTP kimlik bilgilerini yönetmenizi, TLS'yi işlemenizi, DKIM'i kendiniz yapılandırmanızı ve her sağlayıcının kendine özgü özellikleriyle ayrı ayrı başa çıkmanızı gerektirir.

Unipile e-posta API'si bir bulut soyutlama katmanıdır: hesapları OAuth aracılığıyla bağlarsınız (Gmail/Outlook için SMTP kimlik bilgisine gerek yok), tüm sağlayıcılar için tek, tutarlı bir SDK alırsınız ve Unipile iletimi, yeniden denemeleri ve belirteç yenilemeyi yönetir. Karşılığında, gönderileriniz doğrudan bir SMTP bağlantısı yerine Unipile'ın altyapısından geçer.

Evet. unipile-node-sdk TypeScript tanımları ile birlikte gelir. Tam otomatik tamamlama ve tür güvenliği elde edersiniz gönder() yük dahil Alıcı, takip_seçenekleri, ve yanıt türü.

İthalat { UnipileClient } itibaren 'unipile-node-sdk'; // Tam TS türleri - VSCode'da otomatik tamamlama çalışır const müşteri: UnipileClient = yeni UnipileClient(dsn, belirteç); const sonuç = bekle client.email.gönder({ /* yazıldı! */ });

Yüksek hacimli gönderimler için bir eşzamanlılık sınırlayıcısı kullanın (örn. p-limit Birden çok bağlantılı hesap (mümkünse) arasında gönderimleri dağıtın, 5-10 eşzamanlı çağrı ile ve 429 yanıtlarında üstel geri çekilme ekleyin. Her bir bağlantılı e-posta hesabının, sağlayıcı tarafından ayarlanan kendi gönderme sınırları vardır (Gmail: normal hesaplar için günde ~500, Workspace için daha yüksek).

Gerçek toplu/pazarlama e-postaları için (milyonlarca alıcıya), işlemsel ve OAuth tabanlı gönderimler için Unipile'ın yanı sıra özel bir ESP'yi (Mailgun, SendGrid) göz önünde bulundurun.

Next.js: API rotalarını kullanapp/api/eposta-gonder/route.jsveya Sunucu Eylemleri). SDK başlatmasını yalnızca sunucu tarafında tutun.

Nuxt: sunucu rotalarını kullansunucu/api/e-posta-gonder.post.tsSDK yalnızca Node.js'dir, bu nedenle istemci tarafında çalışan bir compostable veya eklentiye konulamaz.

NestJS: oluştur EpostaModülü saran bir servis ile UnipileClient. Gönderimleri tetiklemek için denetleyicilerde, CRON işlerinde veya olay işleyicilerde ihtiyaç duyduğunuz her yere enjekte edin.

Hala sorularınız mı var? Ekibimiz yardım etmek için burada.

tr_TRTR