PHP

Toplu gönderim

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

emails->sendBatch

send_batch.php

$invoices = [    ['number' => 'INV-1042', 'email' => '[email protected]'],    ['number' => 'INV-1043', 'email' => '[email protected]'],]; $messages = []; foreach ($invoices as $invoice) {    $messages[] = [        'from' => '[email protected]',        'to' => $invoice['email'],        'subject' => 'Invoice ' . $invoice['number'],        'text' => 'Your invoice is attached.',    ];} $result = $client->emails->sendBatch($messages, idempotencyKey: 'invoices:2026-09'); echo $result->sent, ' sent, ', $result->failed, ' failed', PHP_EOL; foreach ($result as $item) {    if ($item['status'] === 'error') {        error_log($item['index'] . ' ' . $item['error']['code'] . ' ' . $item['error']['message']);    } else {        echo $item['index'], ' ', $item['email']['id'], PHP_EOL;    }}

sendBatch, her biri emails->send metodunun aldığı diziyle tam olarak aynı biçimde olan ileti dizilerinden oluşan bir liste alır ve bir OpenEmail\Result\BatchResult döndürür. Bunun items alanı her ileti için sırayla bir dizi tutar; her biri ya iletisiyle birlikte ok ya da o iletinin reddedileceği zarfla birlikte error olur ve sonuç üzerinde döngü kurmak bunları dolaşır. 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ı listeyi 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 istisna fırlatmaz. Yalnızca toplu işin bütünüyle ilgili bir sorun istisna fırlatır: boş bir liste, 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->sendBatch

emailsarrayzorunlu: `{"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 `DateTimeInterface` bir ana dönüşür, ek baytları kodlanır ve dizi olmayan bir öğe hiçbir şey gönderilmeden önce `InvalidArgumentException` fırlatır. Boş bir liste, 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 `idempotencyKey:` da tek bir ileti gönderilmeden önce çağrının tamamını reddeder.
idempotencyKeystring: 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.
apiKeystring: Toplu işi istemcinin anahtarı yerine bu anahtarla gönderir.

emails içindeki her ileti

fromstring or arrayzorunlu: Gönderen: çıplak bir adres, `Name <addr@host>` ya da `email` ve `name` içeren bir dizi. 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 or arrayzorunlu: En az bir alıcı; tek bir alıcı istemci tarafından bir liste 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 or array: Varsayılan olarak yoktur ve `to` ile `bcc` ile aynı 50 adreslik toplama sayılır.
bccstring 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 array: 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 dizedir. `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 parça, en fazla bir milyon karakter. İkisi birden gönderilebilir; bu yoldaki her taşıma katmanı tek bir dizgeden tek bir gövde kurar, dolayısıyla `html` varsa o kazanır.
headersarray: 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: İ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. `fopen` ile açılmış bir akış, bir `SplFileInfo` ya da bir PSR-7 akışı geçirin, istemci onu okur ve kodlar; ya da zaten base64 olan bir dize geçirin. Yalnızca `fileId` içeren bir dizi ç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.
templatearray: 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.
scheduledAtDateTimeInterface or string: Bir `DateTimeInterface`, bir ISO 8601 anı ya da `PT1H` gibi bir süre; en az bir saniye sonra ve en fazla 365 gün ileride. Saat içermeyen bir tarih dizesi 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.
cancellableForSecondsint: 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.
trackingarray: `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.
tagsarray: 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:`, `broadcastId:` ve zamanlama penceresine göre filtreler; dolayısıyla bir etiket, onu bulmanın bir yolu değil, elinizdeki bir iletiden okunacak bir şeydir.
translatearray: 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\Result\BatchResult

Sonuç salt okunurdur, items üzerinde IteratorAggregate ve Countable arayüzlerini uygular; bu yüzden foreach ($result as $item) öğeleri dolaşır, count($result) ise onları sayar.

itemsarray: Gönderdiğiniz sırayla her ileti için bir dizi. 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.
sentint or null: 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. Yalnızca yanıt bir sayı taşımadığında null olur.
failedint or null: 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

indexint: Bu öğenin iletisinin gönderdiğiniz liste 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.
emailarray: 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.
errorarray: 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 genişletilebilir bir kümedir, bu yüzden tanımadığınız bir kodu `type` değerine göre ele alın. Burada adı `code`, çünkü bu kodu çözülmüş zarftır; bir istisna ise aynı değeri `errorCode` olarak taşır.
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.