Ruby

Toplu gönderim

`emails.send_batch`: en fazla 100 ileti, öğe başına sonuçlar.

emails.send_batch

send_batch.rb

invoices = [  {number: "INV-1042", email: "[email protected]"},  {number: "INV-1043", email: "[email protected]"}] messages = invoices.map do |invoice|  {from: "[email protected]", to: invoice[:email], subject: "Invoice #{invoice[:number]}", text: "Your invoice is attached."}end result = client.emails.send_batch(messages, idempotency_key: "invoices:2026-09") puts "#{result.sent} sent, #{result.failed} failed" result.items.each do |item|  if item[:status] == "error"    warn "#{item[:index]} #{item.dig(:error, :code)} #{item.dig(:error, :message)}"  else    puts "#{item[:index]} #{item.dig(:email, :id)}"  endend

send_batch, her biri emails.send gövdesiyle tam olarak aynı biçimde olan ileti Hash'lerinden oluşan bir Array alır ve bir OpenEmail::BatchResult döndürür. Bunun items alanı her ileti için sırayla bir Hash tutar; her biri ya iletisiyle birlikte ok ya da o iletinin reddedileceği zarfla birlikte error olur. Hiçbir şey geri alınmaz; bu yüzden 0'dan büyük bir failed sayısı, toplu işi yeniden göndermek için bir neden değil, üzerinde işlem yapılacak bir listedir.

Tek bir idempotency anahtarı toplu işin tamamını kapsar ve sunucu onu her öğe için genişletir; bu yüzden yeniden denenen bir toplu iş, iletileri ilkinin üzerine katlamak yerine her birini yeniden oynatır. Yeniden denerken aynı Array'i aynı sırayla gönderin: yeri değişen bir öğe başka bir konumun anahtarına bağlanır ve bir idempotency_key_reuse hatası olarak döner.

Reddedilen bir ileti hata fırlatmaz. Yalnızca toplu işin bütünüyle ilgili bir sorun hata fırlatır: boş bir Array, 100'den fazla ileti, translate taşıyan 10'dan fazla ileti, bir anahtar ya da kapsam hatası veya bir sunucu arızası. Yarı yolda oluşan bir sunucu arızası önceki öğeler gittikten sonra gelir ve istemci toplu işi aynı anahtarla yeniden dener; bu da o öğeleri iki kez göndermek yerine yeniden oynatır.

Öğeler tek bir istek içinde birbiri ardına gönderilir; bu yüzden anında gönderimlerden oluşan büyük bir toplu iş tek bir send çağrısından belirgin şekilde daha uzun sürer. İstemcinin timeout: değerini geniş tutun.

Parametreler: emails.send_batch

emailsArray<Hash>zorunlu: `{"emails": [...]}` olarak gönderilen ve verilen sırayla tek tek kabul edilen 1 ile 100 arası ileti. Her biri `emails.send` ile aynı işlemden geçer: tek bir alıcı sarılır, bir Time bir ana dönüşür ve ek baytları kodlanır. Boş bir Array, 100'den fazla ileti ya da `translate` taşıyan 10'dan fazla ileti, `emails` üzerinde bir `validation_error` ile çağrının tamamını reddeder. Eksik bir `emails:send` kapsamı ve hatalı biçimlendirilmiş bir `idempotency_key:` da tek bir ileti gönderilmeden önce çağrının tamamını reddeder.
idempotency_keyString: Toplu işi süreçler arasında tekilleştirir. İstemci her durumda her çağrıya yeni üretilmiş bir anahtar ekler, böylece kendi yeniden denemeleri asla iki kez göndermez. Sunucu ise aldığı anahtarı her öğe için `key/0`, `key/1` ve benzeri biçimde, kendi anahtarınızın içeremeyeceği bir karakter olan eğik çizgiyle ayırarak genişletir; böylece yüz iletiyi kapsayan tek bir anahtar onları ilkinin üzerine katlayamaz.
api_keyString: Toplu işi istemcinin anahtarı yerine bu anahtarla gönderir.

emails içindeki her ileti

fromString or Hashzorunlu: Gönderen: çıplak bir adres, `Name <addr@host>` ya da `email` ve `name` içeren bir Hash. Yedek bir gönderen yoktur ve anahtarın bu adrese izni olmalıdır. Bir ret yalnızca o öğeyi, `from_address_forbidden` kodlu bir `permission_error` olarak başarısız kılar.
toString, Hash or Arrayzorunlu: En az bir alıcı; tek bir alıcı istemci tarafından bir Array içine sarılır. `to`, `cc` ve `bcc` toplamında en fazla 50 adres; sayım toplu işin tamamı için değil, ileti başına yapılır.
ccString, Hash or Array: Varsayılan olarak yoktur ve `to` ile `bcc` ile aynı 50 adreslik toplama sayılır.
bccString, Hash or Array: Varsayılan olarak yoktur ve aynı 50 adreslik toplama sayılır. `Bcc`, `headers` içinde ayarlanamayan adlardan biridir; dolayısıyla gizli kopya göndermenin tek yolu budur. Başlık biçimi, adresi gizli tutan alıcı başına zarfı bozardı.
replyToString or Hash: Yanıtların gideceği yer. `headers` işlendikten sonra uygulanır; dolayısıyla orada da ayarladığınız bir `Reply-To` başlığına ikincisini eklemek yerine onun üzerine yazar.
subjectString: En fazla 998 karakter (RFC 5322 satır sınırı); varsayılanı boş bir String'dir. `template` bir konu sağladığında boş bir konu şablonun kendi konusuna geçer.
htmlString: HTML parça, en fazla bir milyon karakter; iki gövde de verildiğinde alıcıların gördüğü parçadır. `html`, `text`, `template` veya `draftId` alanlarından biri zorunludur ve hiçbirini taşımayan bir öğe `html` üzerinde `validation_error` ile başarısız olur.
textString: Düz metin kısmı, en fazla bir milyon karakter. İkisi birden gönderilebilir, ancak bu yoldaki her taşıma katmanı tek bir String'den tek bir gövde oluşturur; bu yüzden `html` varsa o kazanır.
headersHash: Yalnızca `X-*`, `List-*`, Reply-To, Precedence, Auto-Submitted, Importance, Priority ve Feedback-ID. Taşıma katmanının kendisinin ayarladığı her şey (From, To, Bcc, Subject, Message-ID, DKIM ve ARC başlıkları) sessizce atılmaz, `reserved_header` olarak reddedilir. Değerler en fazla 998 karakterdir ve CR, LF ya da NUL içeremez, çünkü ikinci bir satır ikinci bir başlık demektir.
attachmentsArray<Hash>: İleti başına en fazla 20 dosya; satır içi dosyalar çözüldükten sonra toplam 5 MB'dir ve sayım toplu iş başına değil, ileti başına yapılır. `content` ağ üzerinde base64'tür. Baytları ikili bir String, bir IO ya da bir Pathname olarak geçirin, istemci onları kodlar. Yalnızca `fileId` içeren bir Hash çalışma alanında zaten bulunan bir dosyayı belirtir ve satır içi sınırına sayılmaz.
threadIdString: Var olan bir konuşma dizisine yanıt verir, en fazla 256 karakter. Taşıma katmanı In-Reply-To ve References başlıklarını bundan yazar; yanıtın konuşmanın yanına değil içine düşmesini sağlayan şey budur.
draftIdString: Kaydedilmiş bir taslağın içeriğini bu zarfla gönderir; en fazla 256 karakter. Ağa giden, burada oluşturulan alıcılar, konu ve başlıklardır.
templateHash: Kayıtlı bir şablonu kimliğe (`tpl_…`) ya da slug'a göre sunucu tarafında işler; `version` bir revizyonu sabitler, `props` ve `slots` ise onu doldurur. Öğe kabul edildiğinde bir kez kesinleşir ve `html` ya da `text` ile ve `draftId` ile birlikte reddedilir, çünkü bunların her biri iletinin ne içerdiği sorusuna ikinci bir yanıttır.
scheduledAtTime, DateTime or String: Bir Time ya da DateTime, bir ISO 8601 anı ya da `PT1H` gibi bir süre; en az bir saniye sonra ve en fazla 365 gün ileride. Bir Ruby Date o günün UTC gece yarısı anlamına gelir. Öğeler bağımsız olarak zamanlanır, bu yüzden bir toplu iş yüz farklı gönderim zamanı içerebilir.
cancellableForSecondsInteger: Anında bir gönderim için saniye cinsinden bir geri alma penceresi; 0 ile 900 arası, varsayılanı 0. Aynı öğede `scheduledAt` ile birlikte 0'dan büyük her değer reddedilir, çünkü zamanlanmış bir ileti gidene kadar zaten iptal edilebilir.
trackingHash: `opens` ve `clicks`; her biri isteğe bağlıdır ve her biri yalnızca bu ileti için ayarı geçersiz kılar. Belirtmediğiniz bir anahtar, iletinin gönderildiği adresin (ya da onu yakalayan catch-all'un) ayarını izler; bu ayar, o adres açmadıkça kapalıdır.
tagsHash: En fazla 10 etiket; anahtarlar `A-Za-z0-9_-` karakterlerinden 1 ila 64 karakter, değerler en fazla 256 karakter. İletide aynen geri döndürülür ve asla yorumlanmaz: `emails.list` yalnızca `status:`, `from:`, `broadcast_id:` ve zamanlama penceresine göre filtreler; dolayısıyla bir etiket, onu bulmanın bir yolu değil, elinizdeki bir iletiden okunacak bir şeydir.
translateHash: Bu öğeyi başka bir dilde gönderir; kabul anında kesinleşir, böylece giden sözcükler onaylanan sözcüklerdir. Bir toplu işte en fazla 10 öğe bunu taşıyabilir: her biri birkaç model çağrısı harcar ve öğeler sırayla çalışır, bu yüzden daha büyük bir toplu iş gönderimin ortasında sonlandırılırdı. Bunun üzerinde, hiçbir şey gönderilmeden önce çağrının tamamı `emails` üzerinde `too_many_items` olarak reddedilir.

Yanıt: OpenEmail::BatchResult

itemsArray<Hash>: Gönderdiğiniz sırayla her ileti için bir Hash. Hiçbir şey geri alınmaz; bu yüzden bu, bir işlem (transaction) raporu değil, her iletiye ne olduğunun kaydıdır. API, iletilerin hepsi, bir kısmı ya da hiçbiri kabul edilmiş olsun 207 ile yanıt verir; bu yüzden çağrı her durumda döner ve dallanmayı her öğenin `status` değerine göre yapmalısınız.
sentInteger: Kaç öğenin KABUL EDİLDİĞİ; bu, kaçının gittiğiyle aynı şey değildir. Bir öğe `ok` olup yine de `status` değeri `failed` ya da `partial` olan bir `email` taşıyabilir, çünkü kayıt oluştuktan sonra iletiyi reddeden bir taşıma katmanı reddedilmiş bir istek değil, bir teslimat sonucudur.
failedInteger: Kaç öğenin bir `error` taşıdığı. 0'dan büyük bir sayı, toplu işi yeniden göndermek için bir neden değil, üzerinde işlem yapılacak bir listedir. Kabul edilen iletiler zaten gitmiştir.

Her öğe

indexInteger: Bu öğenin iletisinin gönderdiğiniz Array içindeki konumu. Sıralamanın yanı sıra bir anahtar olarak da taşınır; böylece `items` dizisini filtreleyen ya da sıralayan kod yine de hangi iletinin başarısız olduğunu söyleyebilir.
statusString: `ok` ya da `error`. `ok`, `email` taşır; `error`, `error` taşır ve hiçbir öğe ikisini birden taşımaz.
emailHash: Kabul edilen ileti; yalnızca bir `ok` öğesinde ve tekil bir gönderimin döndürdüğü biçimde. Türetilen `Idempotency-Key` zaten var olan bir gönderimle eşleştiğinde `replayed` değeri true olur; bu durumda yeni hiçbir şey gönderilmemiştir ve bu asıl iletidir. `tracking` anahtarı taşımaz, çünkü etkileşim daha sonra bildirilir ve kabul anında bildirilecek bir şey yoktur.
errorHash: Bu tek iletinin neden reddedildiği; yalnızca bir `error` öğesinde. API'nin hata zarfından `docUrl` ve `requestId` çıkarılmış hâlidir: bunlar isteği tanımlar ve istek bir bütün olarak başarılı olmuştur.

Bir öğenin hatası

typeString: Dallanma için kullanılacak kategori: `validation_error`, `permission_error`, `not_found_error`, `conflict_error` ve diğerleri. Bu küme, `code` değerinin aksine dondurulmuştur ve büyümeyecektir.
codeString: Belirli hata: `from_address_forbidden`, `invalid_email_address`, `too_many_recipients`, `reserved_header`, `message_too_large`, `unknown_parameter`. Açık ve eklemelidir; bu yüzden tanımadığınız bir kodu `type` değeri gibi ele alın.
messageString: Bir insan için yazılmış tek cümle; varsa sorunlu değeri adıyla belirtir. Kararlı bir tanımlayıcı değildir. `code` üzerinden dallanın.
paramString: Reddedilen alan, O MESAJIN içinde noktalı bir yol olarak: `to.0`, `from`, `attachments`. Hata hiçbir alanı göstermiyorsa bulunmaz ve asla toplu istekteki konumla öneklenmez; o iş `index` alanınındır.