Ruby

E-posta gönderme

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

emails.send

send_email.rb

email = client.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: Pathname("invoice.pdf")}],  threadId: "CAHk7pQ2x9LmZ4-mail.example.com",  scheduledAt: "PT1H",  tags: {order: "4021"},  tracking: {opens: true, clicks: true}) puts email[:id], email[:status]

to, cc ve bcc bir alıcı ya da alıcılardan oluşan bir Array alır; tek bir alıcı sizin için sarılır. Her biri çıplak bir adres, Name <addr@host> ya da email ve name içeren bir Hash olabilir.

İleti anahtar kelime argümanları olarak ya da tek bir Hash olarak verilir. Bir Hash'in yanındaki anahtar kelime argümanları onunla birleştirilir ve ikisi de aynı alanı belirttiğinde öncelik kazanır; bu yüzden client.emails.send(message, subject: "Re: your invoice") daha önce kurduğunuz bir iletinin tek bir alanını değiştirir. Anahtarlar API'deki adlarını korur; replyTo ve scheduledAt alanlarının camelCase kalmasının nedeni budur. idempotency_key: ve api_key: ise çağrının seçenekleridir ve asla iletinin parçası değildir.

Parametreler

fromString or Hashzorunlu: Gönderen. Çıplak bir adres, `Name <addr@host>` ya da `email` ve `name` içeren bir Hash. Bu anahtarın adına gönderebileceği bir adres olmalıdır; aksi hâlde çağrı 403 `from_address_forbidden` fırlatır. Yedek bir gönderen yoktur, bu yüzden bir gönderim her zaman hangi adresle çıkacağını belirtir.
toString, Hash or Arrayzorunlu: Bir alıcı ya da alıcılardan oluşan bir Array; tek bir alıcı sizin için sarılır. `to`, `cc` ve `bcc` toplamında en fazla 50; daha fazlası 422 `too_many_recipients` verir.
ccString, Hash or Array: 50 alıcı sınırına dahil edilir.
bccString, Hash or Array: Başka birinin aldığı baytlarda asla adı geçmez, çünkü her alıcı için ayrı bir zarf iletilir. Bu alıcılar da 50 sınırına dahildir.
replyToString or Hash: Tek bir adres; Reply-To başlığı olarak gönderilir.
subjectString: En fazla 998 karakter; bu, RFC 5322 satır sınırıdır. Varsayılan olarak boştur ve boş bir konu, şablonun ya da taslağın konusuna geri döner.
htmlString: `html`, `text`, `draftId` veya `template` alanlarından biri zorunludur. `html` ve `text` birlikte verildiğinde alıcıların gördüğü HTML'dir. En fazla 1.000.000 karakter.
textString: Düz metin kısmı, en fazla 1.000.000 karakter.
templateHash: Kayıtlı bir şablonu sunucu tarafında işleyin: bir kimlik ya da slug alan `id` ile isteğe bağlı `version` (bir Integer), `props` ve `slots` içeren bir Hash. `version` bir revizyonu sabitler. İstek kabul edildiğinde yayımlanmış olanı kullanmak için belirtmeyin. Bilinmeyen ya da eksik bir prop, iletide boşluk bırakmak yerine 422 verir.
draftIdString: Kaydedilmiş bir taslağı yazıldığı hâliyle bu zarfla gönderin. `template` ya da `translate` ile birlikte kullanılamaz.
headersHash: Başlık adından String değere eşleme; yalnızca `X-*`, `List-*`, Reply-To, Precedence, Auto-Submitted, Importance, Priority ve Feedback-ID ile sınırlıdır. Taşıma katmanının kendisinin ayarladığı her şey sessizce atılmaz, 422 `reserved_header` ile reddedilir.
attachmentsArray<Hash>: Her biri `filename`, `content` ve isteğe bağlı `contentType` içeren bir Hash ya da yalnızca `fileId` içeren ve çalışma alanında zaten bulunan bir dosyayı (örneğin `files.upload` ile yüklenmiş bir dosyayı) belirten bir Hash. `content` için baytları geçirin, sizin için base64 ile kodlanır. En fazla 20 dosya; satır içi dosyalar çözüldükten sonra toplamda 5 MB ile sınırlıdır. Kayıtlı bir dosya daha büyük olabilir ve bir indirme bağlantısı olarak iletilir.
attachmentDeliveryString: `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.
scheduledAtTime, DateTime or String: UTC ISO 8601 anı olarak gönderilen bir Time ya da DateTime, String olarak bir ISO 8601 anı ya da `PT1H` gibi bir süre. En fazla bir yıl ileri, asla geçmişte değil. `cancellableForSeconds` ile birlikte kullanılamaz. Bir Ruby Date çıplak bir tarih olarak gönderilir ve API bunu o günün UTC gece yarısı olarak okur; bu yüzden saat önemliyse bir Time geçirin.
cancellableForSecondsInteger: 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.
tagsHash: En fazla 10 etiket; anahtarlar harf, rakam, `_` ya da `-` karakterlerinden 1 ile 64 karakter, String değerler en fazla 256 karakter. Her okumada aynen geri döndürülür ve asla yorumlanmaz.
signatureBoolean: Bu iletinin gönderen adresin imzasını taşıyıp taşımayacağı: adresin kendi imzası, yoksa bir catch-all'un yakaladığı adres için catch-all'un imzası, o da yoksa OpenEmail alt bilgisi (o adres kapatmadıysa). Belirtilmezse `html` gövde yazıldığı gibi imzasız gider, yalnızca `text` olan gövde ise imzayı taşır. Bir programın birinin adına gönderdiği postada, örneğin bir makbuz, parola sıfırlama ya da özet için `false` verin; bunların hiçbiri altında bir kişinin imzasını istemez. Şablon gönderimleri ve şifreli gönderimler hiçbir zaman imza taşımaz.
trackingHash: İsteğe bağlı Boolean `opens` ve `clicks` içeren bir Hash: bu iletiye açılma pikseli eklenip bağlantılarının yeniden yazılıp yazılmayacağı. İletinin gönderildiği adres (ya da onu yakalayan catch-all) için izleme açılmadıkça kapalıdır ve burada belirtilen her iki anahtar da, adres nasıl ayarlanmış olursa olsun o tek ileti için kararı verir.
translateHash: Alıcının dilinde gönderir: `to` ve isteğe bağlı `from`, `subject` ve `includeOriginal` içeren bir Hash. `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 kesinleşir, dolayısıyla zamanlanmış bir ileti onaylanan sözcükleri taşır. `draftId` ile birlikte reddedilir.
idempotency_keyString: Bu gönderim için kendi anahtarınız; harf, rakam, `_`, `.`, `:` ya da `-` karakterlerinden oluşan 1 ile 255 karakter. Anahtar yoksa istemci her çağrı için bir anahtar üretir, böylece kendi yeniden denemeleri asla iki kez göndermez; anahtar varsa başka bir süreçte yeniden çalışan bir gönderim tekrarlanmak yerine yeniden oynatılır.
api_keyString: Birkaç çalışma alanı adına gönderim yapan bir süreç için, istemcinin anahtarı yerine bu anahtarla gönderir.

Yanıt

Symbol anahtarlı bir Hash; bu yüzden email[:status] durumu okur.

idString: Gönderim kimliği: `msg_` ve ardından 24 onaltılık karakter. Bunu `get`, `cancel`, `reschedule` ve `get_tracking` için kullanın.
statusString: queued, scheduled, sending, sent, partial, bounced, cancelled veya failed. Çağrının dönmüş olmasına değil buna bakın: anında bir gönderim istek içinde sevk edilir ve genellikle `sent`, `partial` ya da `failed` olarak döner; bekletilen bir gönderim ise `queued` ya da `scheduled` olarak döner. `partial` kendi başına bir durumdur: bazı alıcılar iletiyi almıştır ve bu geri alınamaz, dolayısıyla yeniden denemek yanlış, başarısızlık bildirmek ise yalandır.
modeString: `live` ya da `test`: iletiyi hangi tür anahtarın gönderdiği. Bir test gönderimi kaydedilir ve asla iletilmez. Durumu `sent` olarak görünür ve `transport` değeri `test` olur; bu yüzden doğrulamayı bir gelen kutusu üzerinde değil, yanıt üzerinde yapın.
fromString: Gerçekte yetkilendirilen ve ağa konan adres; bu her zaman istenen adres değildir.
subjectString or nil: Gönderildiği hâliyle.
messageIdString or nil: RFC 5322 Message-ID. MIME oluşana kadar nil. Gönderim hizmeti başlığı çıkışta yeniden yazar; bu yüzden hiçbir geri dönme ya da teslimat raporu bu değeri taşımaz. Bir olay `id` ile geri gelir.
threadIdString or nil: Düştüğü konuşma dizisi.
transportString or nil: İletinin nasıl çıktığı. Sevk edilene kadar nil.
attemptsInteger: Gönderimin kaç kez denendiği.
lastErrorString or nil: Son denemenin neden başarısız olduğu, olduğu gibi.
scheduledAtString or nil: İletinin gitmesi gereken ISO 8601 anı.
cancellableUntilString or nil: Şu an bu andan önce olduğu sürece `cancel` hâlâ çalışır.
sentAtString or nil: İletinin çıktığı ISO 8601 anı.
tagsHash: Gönderdiğiniz şey, aynen geri döndürülür.
sourceString: composer, api, mcp, ai veya queue: hangi yüzeyin istediği. `api` bu istemcidir.
createdAtString: Kaydın yazıldığı ISO 8601 anı.
replayedBoolean: Bir Idempotency-Key zaten var olan bir gönderimle eşleştiğinde true. Yeni hiçbir şey gönderilmedi ve bu, asıl iletinin şu anki hâlidir.
translationHash: Yalnızca çevrilmiş bir iletide ve yalnızca saklanan isteğin tamamının taşındığı yerlerde bulunur: bu yanıtta ve `get` içinde. Tam dil satırları yerine kodlarla birlikte `language`, `languageName`, `detectedSourceLanguage`, `subject` ve `includeOriginal` içerir. Bir liste satırında asla bulunmaz, bu yüzden orada olmaması hiçbir şey ifade etmez.

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.rb

email = client.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"}) p email[:translation]

Bu durumda email[:translation] şunu okur: {language: "de", languageName: "German", detectedSourceLanguage: "en", subject: true, includeOriginal: true}.

Bunu gitmeden önce kimse okumadı. emails.translate aynı gidiş dönüşün bir adım önce durdurulmuş hâlidir. Sonucu bir kişiye gösterin, değiştirmesine izin verin, ardından onayladığını çağrıda hiç translate olmadan gönderin. Onu yeniden geçirmek metni ikinci kez çevirir ve kişinin düzenlemelerini atar.

preview_translation.rb

preview = client.emails.translate(  subject: "Your September invoice",  html: "<p>Invoice attached. Payment is due on the 14th.</p>",  to: "de") puts preview.dig(:language, :native), preview[:subject], preview[:html]print "Send it as it is? [y/N] " if $stdin.gets.to_s.strip.casecmp?("y")  client.emails.send(    from: "[email protected]",    to: "[email protected]",    subject: preview[:subject],    html: preview[:html]  )end

languages.rb

p OpenEmail::LANGUAGES.size current = client.languages.listp current.size p OpenEmail.resolve_language("Deutsch")&.fetch(:code)p OpenEmail.resolve_language("zh-TW")&.fetch(:code)p OpenEmail.language_by_code("DE")&.fetch(:native)p OpenEmail.rtl_language?("ar")

Bu satırlar önce 200'ü, yani bu sürümle gelen satır sayısını, ardından API'nin şu anda kaç satır tuttuğunu, ardından "de", "zh-Hant", "Deutsch" ve true değerlerini yazdırır. Tablo, seçici sırasıyla OpenEmail::LANGUAGES olarak gem'e dahildir: code, label, native, flag ve rtl içeren Hash'lerden oluşan dondurulmuş bir Array; böylece bir dil seçici ilk istekten önce doldurulabilir. languages.list aynı satırları ağdan düz bir Array olarak döndürür; bu sürümle gelenler yerine güncel satırları tercih eden çağıranlar içindir. OpenEmail.resolve_language bir kod, İngilizce bir ad, dilin kendi adı ya da bir takma ad alır (zh-TW artık listelenmeyen bir kodun takma adıdır) ve hiçbir şey eşleşmezse nil döndürür; OpenEmail.language_by_code büyük/küçük harften bağımsız olarak tam bir kodu eşleştirir ve satırlardan on altısı sağdan sola yazılı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.

API'nin eşleştiremediği 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, çalışma alanı bugünkü AI işlemlerini tükettiyse 429 ai_quota_exceeded (UTC gece yarısında sıfırlanır ve yeniden denenmez), sağlayıcı yanıt vermediyse translation_failed. Hiçbiri yedek olarak iletiyi ç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.
Kuyruğa alınmış ya da zamanlanmış çevrilmiş bir ileti onaylanmış metnini korur. emails.reschedule onu yine de taşıyabilir, ancak emails.update yeni bir metni 409 translation_locked ile reddeder; bu yüzden içeriği değiştirmek, iptal edip yeniden göndermek anlamına gelir.

Ekler

content ağ üzerinde base64'tür. Baytları geçirin, sizin için kodlanır: File.binread çağrısının döndürdüğü gibi ikili bir String, açık bir File gibi bir IO ya da sizin için okunan bir Pathname.

attachments.rb

attachments = [  {filename: "invoice.pdf", content: File.binread("invoice.pdf"), contentType: "application/pdf"},  {filename: "report.pdf", content: Pathname("report.pdf")},  {fileId: "file_6bb640f5b99e47deb758f1f5"}] client.emails.send(  from: "[email protected]",  to: "[email protected]",  subject: "Your documents",  text: "Both are attached.",  attachments:)

File.read çağrısının döndürdüğü gibi metin olarak işaretlenmiş bir String'in zaten base64 olduğu varsayılır; base64 olmayan bir String ise hiçbir şey gönderilmeden önce ArgumentError fırlatır. Dosyaları File.binread ile okuyun ya da metin olarak işaretlenmiş gelen baytlar üzerinde .b çağırın.

Aynı kodlamaya başka bir yerde ihtiyacınız olursa OpenEmail.to_base64 kullanılabilir. İkili bir String, bir IO ya da bir Pathname alır ve satır sonu içermeyen katı base64 döndürür.