PHP

Listeleme ve getirme

`emails->list`, `emails->listAll`, `emails->iterate`, `emails->get` ve `emails->listEvents`.

emails->list

list_emails.php

$filters = ['status' => ['queued', 'scheduled'], 'from' => '[email protected]']; $first = $client->emails->list(...$filters, limit: 50);$second = $first->hasMore ? $client->emails->list(...$filters, limit: 50, cursor: $first->nextCursor) : null; echo count($first), ' ', $second === null ? 0 : count($second), PHP_EOL;

Bir sayfa, items, hasMore ve nextCursor içeren bir OpenEmail\Result\Page nesnesidir. Sonraki sayfa için nextCursor değerini aynı filtrelerle cursor: olarak geri geçirin. ...$filters örneğinde olduğu gibi tek bir filtre dizisini her çağrıya yaymak, filtreleri aynı tutar.

emails->iterate ve emails->listAll

iterate_emails.php

foreach ($client->emails->iterate(status: 'failed') as $email) {    error_log($email['id'] . ' ' . ($email['lastError'] ?? ''));} $failures = $client->emails->listAll(status: 'failed', from: '[email protected]');echo count($failures), PHP_EOL;

İkisi de nextCursor değerini sizin için izler. iterate, bir sayfayı yalnızca dolaşma oraya ulaştığında getiren bir Generator döndürür; bu yüzden foreach döngüsünden break ile çıkmak istekleri durdurur. listAll ise tek bir dizi döndürmeden önce her sayfayı dolaşır, bu yüzden ona sonu olan bir filtre verin. Her iki durumda da anahtar kümesine dayalı (keyset) sayfalama kullanılır; böylece dolaşma sırasında gelen bir ileti, bir ofsetin yapacağı gibi bir satırın atlanmasına yol açamaz.

emails->get ve emails->listEvents

get_email.php

$email = $client->emails->get('msg_3f9a1c07d2b84e6a9c5b1f20');echo $email['status'], PHP_EOL;print_r($email['recipients']); $events = $client->emails->listAllEvents('msg_3f9a1c07d2b84e6a9c5b1f20'); foreach ($events as $event) {    echo $event['type'], ' ', $event['createdAt'], PHP_EOL;}

recipients döndüren tek çağrı get'tir: her adres için kendi status, error ve deliveredAt değerlerine sahip bir dizi. Her biri alıcılarını taşıyan elli iletilik bir liste, kimsenin istemediği bir rapor sayfası olurdu.

listEvents bir gönderimin olay geçmişini en eskiden başlayarak okur: email.accepted, email.queued, email.sent, email.delivered, email.bounced, email.opened ve diğerleri; her biri biçimi type değerine bağlı olan bir data dizisi içerir. listAllEvents ve iterateEvents geçmişin tamamını sizin için dolaşır. Webhook'lar aynı olayların bir alt kümesini gerçekleştikçe teslim eder; bu yüzden bir webhook kaçırıldığında bakılacak yer burasıdır.

Parametreler

statusstring or array: Bir ya da birkaç durum (`queued`, `scheduled`, `sending`, `sent`, `partial`, `bounced`, `cancelled`, `failed`); verilenlerden herhangi biriyle eşleşir. `bounced`, iletinin gittiği her alıcıda geri döndüğü anlamına gelir; bazılarında geri dönüp diğerlerine ulaşan bir ileti ise `partial` olarak görünür. Sunucu virgüllere göre böldüğü için istemci bir diziyi virgülle ayrılmış tek bir değer olarak gönderir ve küme dışındaki bir değer, bilinmeyeni adlandıran bir 422 verir.
broadcastIdstring: Yalnızca tek bir toplu gönderimin kopyaları; `broadcasts->send` çağrısından gelen bir `brd_` kimliği. Bir toplu gönderimin ulaştığı her kişi kendine ait bir ileti alır; bu yüzden bu liste, gönderimin kime gittiğini ve her kopyaya ne olduğunu gösterir. `broadcasts->listRecipients` aynı kişileri açılmaları, tıklamaları ve abonelikten çıkmalarıyla birlikte listeler.
fromstring: Kaydedildiği hâliyle, yani küçük harfe çevrilmiş çıplak `addr@host` olarak gönderen adresle tam eşleşme. Kayıt, görünen ad çıkarılarak yazılır; bu yüzden `Acme <[email protected]>` gibi açılı ayraçlı bir adres hiçbir şeyle eşleşmez. Değeriniz karşılaştırmadan önce küçük harfe çevrilir ve bu bir önek ya da alan adı eşleşmesi değil, eşitlik karşılaştırmasıdır.
scheduledFromDateTimeInterface or string: Yalnızca bu an ya da sonrası için zamanlanmış iletiler. `scheduledTo:` ve `status: ['scheduled', 'queued']` ile birlikte, uygulamanın takviminin yaptığı gibi bir zaman aralığında gönderilmeyi bekleyenleri listeler. `scheduledAt` değeri olmayan bir ileti dışarıda kalır. UTC'de bir an olarak gönderilen bir `DateTimeInterface` ya da ofsetiyle birlikte bir ISO 8601 anı geçirin: saat içermeyen bir tarih dizesini bu iki filtre reddeder.
scheduledToDateTimeInterface or string: Yalnızca bu an ya da öncesi için zamanlanmış iletiler. `scheduledTo:` değerinden sonra gelen bir `scheduledFrom:` 422 `invalid_parameter` verir.
limitint: Bu sayfadaki satır sayısı; 1 ile 100 arası, varsayılanı 25. Bu aralığın dışındaki bir değer kırpılmaz, 422 ile reddedilir. `listAll` ve `iterate` üzerinde, getirdikleri her sayfanın boyutudur.
cursorstring: Sayfalamaya başlanacak ileti kimliği (`msg_…`). Ofset değil, anahtar kümesi (keyset): satırlar o iletinin `createdAt` değerinden kesinlikle daha eski olarak döner; böylece sayfa ortasında gelen gönderimler bir satırı sizden öteye itemez. Bu çalışma alanındaki hiçbir iletiyi belirtmeyen bir kimlik 400 `invalid_cursor` verir.
apiKeystring: İstemcinin anahtarı yerine bu anahtarla listeler.

Bazı adreslere daraltılmış bir anahtar yalnızca kapsadığı adreslerden gönderilen iletileri okur ve sayfa bu filtreden sonra kesilir; bu yüzden sonuncusu dışındaki her sayfa yine de limit kadar satır içerir. Anahtarın kapsamadığı bir from: 403 yerine boş bir son sayfa döndürür.

Yanıt: OpenEmail\Result\Page

itemsarray: `createdAt` değerine göre en yeniden eskiye sıralanmış tek sayfalık mesaj; API'nin `data` zarfından çıkarılmıştır. Liste satırları adres başına `recipients` dökümünü asla taşımaz. O döküm `get` üzerindedir.
hasMorebool: Filtreyle eşleşen, bu sayfanın ötesinde başka satır olup olmadığı. İkinci bir sayım sorgusuyla değil, `limit` değerinden bir satır fazla getirilerek yanıtlanır.
nextCursorstring or null: `cursor:` olarak geri geçirilecek kimlik; son sayfada null. `iterate` ve `listAll`, bu değer null olduğunda ya da `hasMore` false olduğunda durur, çünkü devamı olduğunu iddia edip hiçbir cursor belirtmeyen bir sayfa sonsuza dek döngüye girerdi.

Her öğe

objectstring: Bu listenin bir satırında her zaman `email`.
idstring: Bu API'nin kendi kimliği, `msg_…`. Diğer tüm emails çağrılarının aldığı ve bir cursor'ın belirttiği değer budur.
statusstring: Mesajın yaşam döngüsünde nerede olduğu. `partial`, başarısızlığın bir türü değil kendi başına bir durumdur: bazı alıcılar mesajı almıştır ve bu geri alınamaz, dolayısıyla yeniden denemek yanlıştır. `bounced`, mesajın gönderildikten sonra her alıcıdan geri döndüğü, yani kimsenin almadığı anlamına gelir; `get` içindeki her alıcı nedenini söyler.
modestring: `live` veya `test`; gönderen anahtardan alınır. Test gönderimi burada kaydedilir ve asla iletilmez.
fromstring: Gönderimin yetkilendirildiği adres; çıplak ve küçük harfe çevrilmiş olarak saklanır, bu yüzden `from` üzerinde verilen bir görünen ad ağa yine gider ama burada tutulmaz. Dizi değil düz bir dizedir, çünkü bu yetkilendirilmiş kimliktir: bir anahtarın gönderim kapsamı dışındaki, ne sahip olduğu bir alan adında olan ne de anahtarda adı geçen bir adres 403 ile reddedilir; asla sessizce kapsamdaki bir adresle değiştirilmez.
subjectstring or null: Saklandığı hâliyle konu. Konusuz kaydedilmiş bir iletide null.
messageIdstring or null: Bizim kimliğimiz değil, RFC 5322 Message-ID. MIME oluşana kadar null'dır ve gönderim hizmeti tarafından çıkışta yeniden yazılır; bu yüzden daha sonraki bir geri dönme ya da DSN farklı bir kimlik taşır ve bunun yerine `id` ile ilişkilendirilir.
threadIdstring or null: Verilmiş ya da atanmışsa bu iletinin ait olduğu konuşma dizisi. Aksi hâlde null.
transportstring or null: Baytların nasıl çıktığı. Sevk edilene kadar null. Saklanan kayıtlar artık kullanılmayan taşıma katmanlarını hâlâ adlandırabilir; bu yüzden bilmediğiniz bir değeri bir hata olarak değil, bir bilgi olarak ele alın.
attemptsint: Mesaj için kaç gönderim denemesi yapıldığı; ilkinden önce 0.
lastErrorstring or null: Bir insan için yazılmış en son sevk hatası. Hiçbir şey başarısız olmadıkça null.
scheduledAtstring or null: İletinin çıkması gereken an, ISO 8601 anı olarak. Yalnızca iptal penceresi olmayan anında bir gönderimde null: pencere kısa bir gecikmeden başka bir şey değildir, bu yüzden `cancellableForSeconds` de bu alanı doldurur; bu durumda satırın `status` değeri `scheduled` değil, `queued` olur.
cancellableUntilstring or null: Mesajın gitmesi gereken an; ertelenmiş her gönderimde `scheduledAt` ile aynı değeri, ertelenmemiş bir gönderimde ise null taşır. Sunucunun yaptığı sınama değil, gösterilecek bir zaman damgasıdır: `cancel`, `status` üzerinden dallanır ve bir mesajı yalnızca hâlâ `queued` veya `scheduled` iken durdurur.
sentAtstring or null: İletinin gittiği an. Sevk tamamlanana kadar null'dır; dallanma için bu alanın değil, `status` alanının kullanılmasının nedeni budur.
tagsarray: Gönderimde verilen etiketler; olduğu gibi geri döndürülür ve asla yorumlanmaz. Her zaman bir dizidir (hiçbiri ayarlanmadıysa boş, asla null değil) ve yalnızca geri döndürülür: bu liste `status`, `from`, `broadcastId` ve zamanlama penceresine göre filtreler; bu yüzden bir etiket, bir iletiyi bulmanın yolu değil, iletiden okunacak bir şeydir.
broadcastIdstring or null: Bu iletinin kopyası olduğu `brd_` toplu gönderimi ya da tek başına gönderilmiş bir ileti için null.
sourcestring: Gönderimi hangi yüzeyin istediği: `composer`, `api`, `mcp`, `ai` veya `queue`. `api` bu istemcidir.
createdAtstring: Gönderim kaydının ne zaman yazıldığı; bu, gönderimden öncedir. Listenin sıraladığı ve bir cursor'ın karşılaştırdığı alan budur.
trackingarray: Etkileşim özeti; yalnızca iletisi izlenmiş bir satırda bulunur, diğerlerinde yoktur. Yokluğu “bu izlendi mi” sorusunun yanıtıdır; 0 değerindeki bir `openCount` ise “kimse açmadı” olarak okunurdu; bu yüzden anahtarın var olduğunu varsaymak yerine onu `?? null` ile okuyun.
translationarray: Bir liste satırında asla bulunmaz: çeviri kaydı, listenin bilerek getirmediği saklanan istekte yer alır. Buradaki yokluğu, mesajın çevrilip çevrilmediği hakkında hiçbir şey söylemez. `get` çağrısına sorun.

Bir öğenin izlemesi

opensbool: Bu mesajın bir pikselle gidip gitmediği. Hesap ayarının şu anda ne dediği değil, bu mesaja ne uygulandığı.
clicksbool: Bu iletinin bağlantılarının yeniden yazılıp yazılmadığı. Gövdede yeniden yazılacak bağlantı yoksa false, çünkü o durumda hiçbir şey değişmemiştir.
openedbool: Sayılan herhangi bir açılmanın kaydedilip kaydedilmediği; 0'dan büyük `openCount` değerinden türetilir.
clickedbool: Sayılan herhangi bir tıklamanın kaydedilip kaydedilmediği; 0'dan büyük `clickCount` değerinden türetilir.
openCountint: Bir insanın yol açtığına inanılan açılmalar, mesajın her kopyası üzerinden toplanır. Tarayıcı botları ve gizlilik vekilleri kaydedilir ama hariç tutulur; otuz saniye içindeki tekrarlı istekler tek bir açılmaya indirgenir.
clickCountint: Sayılan tıklamalar, kopyalar üzerinden toplanır. Mesaj başına değil bağlantı başına tekilleştirilir, çünkü saniyeler arayla iki bağlantıya tıklamak bir tekrar değil iki ayrı eylemdir.
firstOpenAtstring or null: Kopyalar arasındaki en erken sayılan açılma; hiç yoksa null. Makine istekleri bunu asla değiştirmez.