SDK

E-posta gönder

`emails.send`: tek mesaj, şimdi veya sonra.

emails.send

send-email.ts

const email = await openemail.emails.send({  from: { email: '[email protected]', name: 'Acme Billing' },  to: ['[email protected]', 'Grace <[email protected]>'],  cc: '[email protected]',  bcc: [{ email: '[email protected]' }],  replyTo: '[email protected]',  subject: 'Your September invoice',  html: '<p>Invoice attached.</p>',  text: 'Invoice attached.',  headers: { 'X-Campaign': 'invoices' },  attachments: [{ filename: 'invoice.pdf', content: pdfBytes }],  threadId: 'thread_…',  scheduledAt: 'PT1H',  tags: { order: '4021' },  tracking: { opens: true, clicks: true },})

to, cc ve bcc bir veya birden çok alıcı alır; tek bir alıcı sizin için diziye sarılır. Her biri çıplak bir adres, Name <addr@host> veya { email, name } olabilir.

Parametreler

fromRecipientInputzorunlu: Gönderen. Çıplak bir adres, `Name <addr@host>` veya bir nesne. Bu anahtarın gönderebileceği bir adres olmalıdır. Yedek gönderen yoktur, çünkü yedek, çalışma alanının varsayılan adresi olurdu ve bu adres, adresler gelip gittikçe değişir.
toRecipientInput | RecipientInput[]zorunlu: Bir veya birden çok alıcı; tek bir alıcı sizin için diziye sarılır. to, cc ve bcc toplamında en fazla 50.
ccRecipientInput | RecipientInput[]: 50 alıcı sınırına dahil edilir.
bccRecipientInput | RecipientInput[]: Başka kimsenin aldığı baytlarda asla adı geçmez, çünkü alıcı başına bir zarf iletilir.
replyToRecipientInput: Tek bir adres; Reply-To başlığı olarak gönderilir.
subjectstring: En fazla 998 karakter, RFC 5322 satır sınırı. Varsayılanı boştur.
htmlstring: html, text, draftId veya template alanlarından biri zorunludur. html ve text birlikte verildiğinde alıcıların gördüğü HTML'dir.
textstring: Düz metin parça.
template{ id, version?, props?, slots? }: Saklanan bir şablonu sunucu tarafında işler. `version` sürümü sabitler; belirtmezseniz istek kabul edildiğinde yayımda olan sürüm kullanılır. Bilinmeyen veya eksik bir özellik, mesajda bir boşluk değil 422 verir.
draftIdstring: Kaydedilmiş bir taslağı bu zarf altında gönderir.
headersRecord<string, string>: `X-*`, `List-*`, Reply-To, Precedence, Auto-Submitted, Importance, Priority ve Feedback-Id. Taşıma katmanının kendi ayarladığı her şey sessizce düşürülmek yerine reddedilir.
attachmentsAttachmentInput[]: `{ filename, content, contentType? }` ya da çalışma alanında zaten bulunan bir dosyayı gösteren `{ fileId }`. content için bayt geçirin, sizin için base64'e kodlanır. 20 dosya; satır içi dosyalar çözüldükten sonra toplam 5 MB ile sınırlıdır. Saklanan bir dosya daha büyük olabilir ve indirme bağlantısı olarak gider.
attachmentDeliveryAttachmentDeliveryMode: `mime`, `link` veya `auto`. `auto`, etkin bir dosya alan adı olan bir alan adında dosyaları 2 MB'ı aştıklarında indirme bağlantısı olarak, aksi hâlde mesajın içinde taşır. Belirtilmezse posta kutusu ayarı geçerli olur ve onun varsayılanı `auto`'dur.
threadIdstring: Var olan bir konuşma dizisine yanıt verir. Taşıma katmanı In-Reply-To ve References başlıklarını yazar.
scheduledAtDate | string: Bir Date, bir ISO-8601 anı veya `PT1H` gibi bir süre. En fazla bir yıl sonrası, asla geçmiş değil. cancellableForSeconds ile birlikte kullanılamaz.
cancellableForSecondsnumber: 0 ile 900 arası. Anlık bir gönderimde geri alma penceresi: yazma ekranının geri alma mekanizması, koda gömülmek yerine dışarı açılmış hâli.
tagsRecord<string, string>: En fazla 10 etiket; aynen geri döndürülür ve filtrelenebilir. Asla yorumlanmaz.
signatureboolean: Bu mesajın, gönderildiği adresin imzasını taşıyıp taşımadığı; bu imza o adresin kendi imzası ya da yoksa Tüm adresler için ayarlanmış olandır. Varsayılanı true'dur, çünkü imza mesajı gönderen istemciye değil adrese aittir. Bir programın birinin adına gönderdiği postalar için `false` verin; makbuz, parola sıfırlama veya özet gibi, hiçbiri altında bir insanın imzasını istemez.
tracking{ opens?, clicks? }: Bu mesaja açılma pikseli eklenip bağlantılarının yeniden yazılıp yazılmayacağı. Çalışma alanı sahibi, mesajın gönderildiği adres veya Tüm adresler için izlemeyi kapatmadıkça açıktır ve burada belirtilen her iki alan da, adres nasıl ayarlanmış olursa olsun o tek mesaj için kararı verir.
translate{ to, from?, subject?, includeOriginal? }: Alıcının dilinde gönderir. `to` bir kod, İngilizce bir ad veya dilin kendi adını alır; `subject` ve `includeOriginal` varsayılan olarak true'dur. İstek kabul edildiğinde çözümlenir, dolayısıyla zamanlanmış bir mesaj onaylanan sözcükleri taşır. `draftId` ile birlikte kullanılamaz.

Yanıt

idstring: Gönderim id'si, `msg_…`. Onu `get`, `cancel`, `reschedule` ve `getTracking` için kullanın.
statusEmailStatus: queued, scheduled, sending, sent, partial, cancelled veya failed. Promise'in çözülmüş olmasına değil buna bakın. `partial` kendi başına bir durumdur: bazı alıcılar mesajı almıştır ve bu geri alınamaz, dolayısıyla yeniden denemek yanlış, başarısızlık bildirmek ise yalandır.
mode'live' | 'test': Hangi tür anahtarın gönderdiği. Test gönderimi kaydedilir ve asla iletilmez.
fromstring: Gerçekte yetkilendirilen ve ağa konan adres; bu her zaman istenen adres değildir.
subjectstring | null: Gönderildiği hâliyle.
messageIdstring | null: RFC 5322 Message-ID. MIME oluşana kadar null. Gönderim servisi başlığı çıkışta yeniden yazar; dolayısıyla hiçbir geri dönüş veya teslim raporu bu değeri taşımaz. Bir olayın geri döndüğü değer `id`'dir.
threadIdstring | null: Düştüğü konuşma dizisi.
transportstring | null: Mesajın nasıl gittiği. Gönderime kadar null.
attemptsnumber: Gönderimin kaç kez denendiği.
lastErrorstring | null: Son denemenin neden başarısız olduğu, olduğu gibi.
scheduledAtstring | null: Gitmesi gereken ISO anı.
cancellableUntilstring | null: Şu an bundan önce olduğu sürece iptal hâlâ çalışır.
sentAtstring | null: Gittiği ISO anı.
tagsRecord<string, string>: Gönderdiğiniz şey, aynen geri döndürülür.
sourceEmailSource: composer, api, mcp, ai veya queue: hangi yüzeyin istediği. `api` bu istemcidir.
createdAtstring: Kaydın yazıldığı ISO anı.
replayedboolean: Bir Idempotency-Key, zaten var olan bir gönderimle eşleştiğinde true olur. Yeni bir şey gönderilmemiştir ve bu, özgün mesajdır.
translationEmailTranslationResource | undefined: Yalnızca çevrilmiş bir mesajda ve yalnızca saklanan isteğin tamamının taşındığı yerlerde bulunur: bu yanıt ve `get`. `{ language, languageName, detectedSourceLanguage, subject, includeOriginal }`; hepsi dil satırları değil kodlardır. Bir liste satırında hiç bulunmaz, dolayısıyla oradaki yokluğu hiçbir yönde bir şey söylemez.

Alıcının dilinde

translate, mesajı gitmeden önce bir başkasının dilinde yazar. Gövde ve (siz kapatmadıkça) konu, API isteği kabul ettiğinde çevrilir ve ortaya çıkan metin gidenin ta kendisidir: üretilemeyen bir çeviri, mesajı sizin yazdığınız dilde göndermek yerine gönderimi reddeder.

translate.ts

const email = await openemail.emails.send({  from: '[email protected]',  to: '[email protected]',  subject: 'Your September invoice',  html: '<p>Invoice attached. Payment is due on the 14th.</p>',  translate: { to: 'de' },}) console.log(email.translation)// { language: 'de', languageName: 'German', detectedSourceLanguage: 'en', subject: true, includeOriginal: true }

Kimse gitmeden önce onu okumadı. emails.translate, aynı gidiş dönüşün bir adım önce durdurulmuş hâlidir. Sonucu bir insana gösterin, değiştirmesine izin verin, sonra onun onayladığı metni çağrıda hiç translate olmadan gönderin. Yeniden geçirmek ikinci kez çeviri yapar ve o kişinin düzenlemelerini çöpe atar.

preview-translation.ts

const preview = await openemail.emails.translate({  subject: 'Your September invoice',  html: '<p>Invoice attached. Payment is due on the 14th.</p>',  to: 'de',}) console.log(preview.language.native, preview.detectedSourceLanguage) const approved = await showToSomebody(preview) await openemail.emails.send({  from: '[email protected]',  to: '[email protected]',  subject: approved.subject,  html: approved.html,})

render-picker.ts

import { LANGUAGES, isRtlLanguage, languageByCode, openemail, resolveLanguage } from '@openemail/sdk' LANGUAGES.length // 200 const current = await openemail.languages.list() resolveLanguage('Deutsch')?.code // 'de'resolveLanguage('zh-TW')?.code // 'zh-Hant'languageByCode('DE')?.native // 'Deutsch'isRtlLanguage('ar') // true

Tablo, seçici sırasıyla pakete gömülüdür; böylece bir seçici ilk istekten önce doldurulabilir. languages.list(), ağdan gelen aynı satırları düz bir dizi olarak döndürür; bu, bu sürümle gelenler yerine güncel olanları tercih eden çağıranlar içindir. resolveLanguage bir kodu, İngilizce adı, dilin kendi adını veya bir takma adı alır (zh-TW, artık listelenmeyen bir kodun takma adıdır); languageByCode büyük/küçük harf duyarsız olarak tam kod eşleşmesi yapar ve satırların on altısı sağdan soladır. native, label ve code alanlarında birlikte arayın, önce native değerini gösterin ve kodu saklayın.

emails.translate otomatik olarak yeniden denenmez. Model çağrısı harcar ve hiçbir şey yazmaz; dolayısıyla idempotent kılınacak bir şey yoktur ve yanıtsız kalan bir isteğin ardından yeniden denemek yalnızca aynı yanıtı iki kez satın almak olur.

Hiçbir şeye çözümlenmeyen bir dil, hiçbir şey gönderilmeden önce translate.to üzerinde bir validation_error verir.
30.000 karakteri aşınca translation_too_long, kurulumda yapılandırılmış bir AI yoksa translation_not_configured, sağlayıcı yanıt vermediyse translation_failed. Hiçbiri yedek olarak mesajı çevrilmemiş hâlde göndermez.
template ile birlikte çalışır: çevrilen şey İŞLENMİŞ çıktıdır, dolayısıyla saklanan tek bir gövde, müşterilerinizin okuduğu her dile hizmet eder. Tam bir belge üreten bir şablon doctype'ını, <style> bloklarını ve @font-face kurallarını korur: modele yalnızca gövde gider, geri kalanı çevresine geri konur. Zaten hiçbir yerde görüntülenmeyen <title> öğesine dokunulmaz.
Yeniden denemenin ek bir maliyeti yoktur. Çeviri, idempotency parmak izinin parçası değildir (istek ise translate dahil parçasıdır); dolayısıyla yanıtsız kalan bir gönderimi aynı Idempotency-Key ile yeniden denemek, ikinci kez çevirip göndermek yerine zaten var olan mesajı yeniden oynatır.
Kuyrukta bekleyen veya zamanlanmış, çevrilmiş bir mesaj, metin değişikliklerine karşı dondurulmuştur. emails.reschedule onu yine de erteleyebilir; ne söylediğini değiştirmek ise iptal edip yeniden göndermek demektir.

Ekler

content ağ üzerinde base64'tür. Bayt geçirin, sizin için kodlanır.

attachment.ts

attachments: [  { filename: 'invoice.pdf', content: pdfBytes, contentType: 'application/pdf' },]

Başka bir yerde gerekirse toBase64 dışa aktarılmıştır. Parçalara bölerek çalışır; btoa(String.fromCharCode(...bytes)) ise bölmez. O yöntem yaklaşık 100 kB'ı aşan her şeyde çöker ve test ettiğiniz dosyada değil, gerçek dosyada çöker.