Kitleler
`audiences->list`, `get`, `create`, `update`, `delete`, `empty`, `growth`, `listContacts`, `addContact`, `addContacts`, `importContacts`, `removeContact` ve `removeContacts`.
Her yöntem
$everyone = null; foreach ($client->audiences->listAll() as $audience) { if ($audience['builtin'] === 'default') { $everyone = $audience; }} $list = $client->audiences->create([ 'name' => 'Product updates', 'description' => 'Customers who asked to hear about releases',]); $client->contacts->create(['email' => '[email protected]', 'name' => 'Grace Hopper']);$client->audiences->addContact($list['id'], ['email' => '[email protected]']); $bulk = $client->audiences->addContacts($list['id'], ['emails' => ['[email protected]', '[email protected]']]); $imported = $client->audiences->importContacts($list['id'], [ 'contacts' => [['email' => '[email protected]', 'name' => 'Katherine Johnson']],]); $members = $client->audiences->listAllContacts($list['id'], q: 'grace', sort: 'added-newest', limit: 200); $growth = $client->audiences->growth(audienceIds: [$list['id']], days: 30); $client->audiences->update($list['id'], ['name' => 'Release notes']);$client->audiences->removeContact($list['id'], '[email protected]');$client->audiences->removeContacts($list['id'], ['emails' => ['[email protected]']]);$client->audiences->empty($list['id']);$client->audiences->delete($list['id']); echo $everyone['contactCount'] ?? 0, ' contacts in all', PHP_EOL;echo implode(', ', $bulk['missing']), ' ', $imported['created'], ' ', count($members), ' ', $growth['totals']['added'], PHP_EOL;Bir kitle, bu çalışma alanındaki kişilerin adlandırılmış bir listesidir. Her kişi, var olduğu andan itibaren yerleşik varsayılan kitlededir ve bu satırı adlandıran builtin alanıdır. Geri kalanları oluşturmak, doldurmak ve silmek size kalmıştır. Dallanmayı herkesin değiştirebileceği ada göre değil, builtin alanına göre yapın.
Tek bir kitle üzerindeki bir çağrı, kitlenin kimliğini ilk argüman olarak alır; removeContact ise adresi ikinci argüman olarak alır. Filtreler ve seçenekler camelCase biçiminde adlandırılmış argümanlardır (audienceIds:, offsetMinutes:); bir istek gövdesi ise anahtarları API'nin adlarını koruyan tek bir dizidir (emails, contacts). Bir yanıt, API'nin camelCase adlarıyla anahtarlanmış bir dizidir; bu yüzden $audience['contactCount'] sayıyı okur.
Bir ya da daha fazla kitleye, Toplu gönderimler sayfasında anlatılan $client->broadcasts->send ile gönderin. Bir kişiyi bir kitleye koymak kişiye değil kitleye yapılan bir yazmadır; bu yüzden denetlenen tek kapsam audiences:write'tır. İstisna importContacts'tır. Kişi oluşturduğu için contacts:write de gerektirir.
addContact zaten kişi olan bir adresi alır ve kişi olmayanı ValidationException olarak fırlatılan 422 contact_not_found ile reddeder. Onu önce $client->contacts->create ile kaydedin. Birini iki kez eklemek, asıl addedAt değerini taşıyan mevcut üyelikle yanıt verir; bu yüzden çağrıyı yeniden denemek güvenlidir ve istemci bir ağ hatasından sonra onu yeniden dener.
Varsayılan kitle diğerleri gibi yeniden adlandırılabilir ve açıklanabilir, ancak silinemez ve içinden kişi çıkarılamaz. İkisi de isConflict() değeri true olan bir ConflictException olarak fırlatılan 409 audience_immutable ile reddedilir. Kişinin gitmesini istiyorsanız kişiyi silin.
Yanıt: bir kitle
list bunlardan bir sayfayı items, hasMore ve nextCursor içeren bir OpenEmail\Result\Page olarak döndürür: önce varsayılan kitle, ardından diğerleri en yeniden eskiye. limit: en fazla 100'e kadar istemedikçe bir sayfa 25 kitle içerir. listAll tüm kitleleri tek bir dizi içinde döndürür, iterate ise kitleleri birer birer veren bir Generator döndürür. get, create ve update her biri tek bir kitle döndürür. listContacts ise bunun yerine bir kişi sayfası döndürür: üyelik kayıtları değil, her birinin katıldığı tarihle birlikte kişilerin kendileri; yanında listAllContacts ve iterateContacts bulunur.
idstring- Kalıcı tanıtıcı: `aud_` ve ardından 24 onaltılık karakter. Adlar benzersiz değildir, bu yüzden saklanan yapılandırmaya girmesi gereken değer budur.
namestring- Yazarken kırpılır, 1 ila 120 karakter. İki kitle aynı adı taşıyabilir, çünkü bir kitleye id'siyle erişilir.
descriptionstring or null- Listeyi daha sonra okuyacak kişi için serbest metin. Kimse bir şey yazmadıysa null'dır ve `update` üzerinde `'description' => null` onu temizler.
builtinstring or null- Her çalışma alanında tam olarak bir satırda, yani her kişiyi içeren kitlede `default`; birinin oluşturduğu her kitlede null. Daha sonra eklenecek yerleşik bir kitle varsayılan kitleyle karıştırılmasın diye null olup olmadığını denetlemek yerine `'default'` ile karşılaştırın.
contactCountint- Kitledeki kişi sayısı; önbelleğe alınmak yerine okuma anında sayılır. Bir `contacts->create` çağrısının iki yanındaki iki okuma bir fark gösterir.
lastContactAtstring or null- ISO 8601 UTC; en son katılan kişinin bu kitleye katıldığı an. Kitle boşken null.
createdAtstring- ISO 8601 UTC; kitlenin oluşturulduğu an. Varsayılan kitleden sonraki liste sırasını belirler.
updatedAtstring- ISO 8601 UTC; yeniden adlandırma ya da açıklama değişikliğiyle güncellenir. Üyelik değişiklikleri ona dokunmaz.
Parametreler: audiences->listContacts
limitint- Sayfa başına kişi sayısı; 1 ile 200 arasında bir tam sayı, varsayılanı 50.
cursorstring- Önceki sayfanın `nextCursor` değeri; aynı `q:`, `source:`, `sort:` ve `statuses:` ile gönderilir. Bu kitlede olmayan bir kişiyi belirten bir cursor, `InvalidRequestException` olarak fırlatılan bir 400 `invalid_cursor` verir.
qstring- Adı ve adresi arar, en fazla 200 karakter. İlk sayfada hiçbir şey tam eşleşmezse bunun yerine yakın yazımlar döner ve sonraki sayfalar da aynı şekilde eşleşmeye devam eder.
sourcestring- Birinin bilerek kaydettiği kişiler için `manual`, uygulamanın yazma ekranının kaydettikleri için `auto`. Kitledeki herkes için belirtmeyin.
sortstring- `last-heard-newest` (varsayılan) ve `last-heard-oldest`, `lastSeenAt` değerine göre sıralar; hiç posta gönderilmemiş kişiler ilkinde en sonda, ikincisinde en başta yer alır. `added-newest` ve `added-oldest` her kişinin bu kitleye katıldığı zamana göre sıralar; `name` ise büyük/küçük harfi yok sayar ve adı olmayan bir kişiyi adresine göre sıralar.
statusesstring or array- `['subscribed']` abonelikten çıkmamış üyeleri, `['unsubscribed']` ise çıkmış olanları tutar. Kitledeki herkes için belirtmeyin, boş bir dizi geçirin ya da ikisini birden belirtin. `OpenEmail\Constants\AudienceMemberStatuses` değerleri tutar ve istemci bunları virgülle birleştirerek `status` sorgu parametresi olarak gönderir.
Yanıt: bir kitledeki bir kişi
listContacts kişi dizilerinden oluşan bir OpenEmail\Result\Page döndürür; listAllContacts ve iterateContacts aynı adlandırılmış argümanlarla her sayfayı dolaşır. Her satır, alanları Kişiler sayfasında anlatılan contacts->list biçiminde bir kişidir ve iki alan daha içerir. Bir kitleyi dışa aktarmanın yolu her sayfayı dolaşmaktır.
addedAtstring- ISO 8601 UTC; kişinin bu kitleye katıldığı an. Bir kişiyi çıkarıp yeniden eklemek bu zamanı sıfırdan başlatır.
unsubscribedAtstring or null- ISO 8601 UTC; kişinin bu kitleye gönderilen bir toplu gönderimden abonelikten çıktığı an; abone olduğu sürece null. Abonelikten çıkmış bir kişi kitlede kalır ve kitleye yapılan toplu gönderimler onu atlar. Onu çıkarıp yeniden eklemek yeniden abone yapar.
Toplu ekleme ve çıkarma
addContacts ve removeContacts, emails alanı 1 ile 200 arası adresten oluşan bir liste olan bir dizi alır ve tek bir istekte tek bir kitleyi değiştirir. addContacts asla kişi oluşturmaz. Kişi olmayan bir adres missing içinde döner; kişileri oluşturan çağrı importContacts'tır. İkisini de tekrarlamak güvenlidir; bu yüzden istemci bir ağ hatasından sonra onları yeniden dener ve bir yeniden deneme başarısız olmak yerine aynı kişileri zaten işlenmiş olarak bildirir.
Varsayılan kitleye ekleme added değeri 0 olarak yanıt verir, çünkü her kişi zaten içindedir; üzerinde removeContacts ise 409 audience_immutable ile reddedilir. Birini bir kitleden çıkarmak onu adres defterinde, varsayılan kitlede ve diğer kitlelerinde bırakır.
audienceIdstring- Çağrının değiştirdiği kitle, iki sonuçta da.
addedint- `addContacts` sonucunda: bu çağrının oluşturduğu yeni üyelikler.
unchangedint- `addContacts` sonucunda: zaten kitlede olan kişiler. Onlar için hiçbir şey yazılmadı.
removedint- `removeContacts` sonucunda: bu çağrının kaldırdığı üyelikler.
notInAudiencearray- `removeContacts` sonucunda: kitlede olmayan, bu yüzden başlarına hiçbir şey gelmeyen kişiler.
missingarray- İkisinde de: bu çalışma alanında kişi olmayan adresler, küçük harfle ve tekrarsız.
İçe aktarma
importContacts, kitle sayfasındaki CSV içe aktarmasıdır. contacts alanı, her biri bir email ve isteğe bağlı bir name içeren 1 ile 500 arası diziden oluşan bir liste olan bir dizi alır. Doğru biçimlendirilmiş her adres henüz kişi değilse kişi olur ve hepsi kitleye düşer. Daha uzun bir listeyi birkaç çağrıda gönderin. audiences:write ve contacts:write gerektirir; ikisinden birine sahip olmayan bir anahtar, istisna üzerinde isScopeMissing() değeri true olan 403 insufficient_scope ile reddedilir.
Zaten kişi olan bir adres yeniden kullanılır ve adını korur; buradaki bir name yalnızca boş olan bir adı doldurur. Yeni bir kişi manual olarak kaydedilir ve varsayılan kitleye de katılır; defterden silinmiş bir adres ise geri gelir. Aynı satırları yeniden göndermek hiçbir şeyi iki kez oluşturmaz; bu yüzden istemci bir ağ hatasından sonra çağrıyı yeniden dener.
audienceIdstring- Satırların girdiği kitle.
createdint- Bu çağrının kaydettiği yeni kişiler.
addedint- Bu kitledeki yeni üyelikler; zaten var olan ve henüz kitlede olmayan kişiler de sayılır.
skippedint- Adres hatalı biçimli olduğu için içe aktarılmayan satırlar.
invalidarray- Hatalı biçimli adresler, tam gönderildikleri gibi.
Boşaltma
empty($id) tek bir istekte bir kitledeki tüm kişileri çıkarır ve kitleyi şu anki hâliyle, contactCount değeri 0 olarak ve kaldırılan üyelik sayısı olan removed ile birlikte döndürür. Kitle kimliğini, adını ve açıklamasını korur; her kişi de adres defterinde ve diğer kitlelerinde kalır.
Geri alınamaz ve listede kimlerin olduğu hiçbir yere kaydedilmez; bu yüzden listeyi geri isteyebilecekseniz önce listAllContacts ile dolaşın. Varsayılan kitle boşaltılamaz ve çağrı 409 audience_immutable ile reddedilir. İstemci bir ağ hatasından sonra empty çağrısını yeniden denemez, çünkü ikinci bir çağrı removed değeri 0 olarak başarılı olur. Bir yanıt kaybolduysa kitleyi get ile okuyun.
Büyüme
growth, şu anda biten bir pencere boyunca her kitleye kaç kişinin katıldığını ve bu pencerede kaçının abonelikten çıktığını gün, saat ya da dakikaya göre okur. Kitleler sayfasındaki grafik budur. Adlandırılmış argümanlar alır, audiences:read gerektirir ve tek bir dizi döndürür.
$growth = $client->audiences->growth( audienceIds: ['aud_9f2c4b7e1a0d63d84c5f2e7b'], days: 90, grain: 'day', offsetMinutes: intdiv((int) date('Z'), 60),); echo $growth['totals']['added'], ' joins since ', $growth['since'], PHP_EOL; foreach ($growth['series'] as $series) { echo $series['name'], ': ', $series['before'], ' before the window, ', $series['total'], ' now', PHP_EOL;}Bir kitle birinin ne zaman katıldığını kaydeder, ne zaman ayrıldığını asla kaydetmez; bu yüzden her sayı bugün hâlâ listede olan kişileri katılım tarihlerine göre sayar ve bir çizgi hiçbir zaman düşmez. Katılıp sonra ayrılan bir kişi sayıların hiçbirinde yer almaz.
Parametreler
audienceIdsstring or array- Bir liste ya da virgülle ayrılmış tek bir dize olarak verilen ve virgülle birleştirilerek gönderilen en fazla 50 kitle kimliği. Tüm kitleler için belirtmeyin ya da boş bir dizi geçirin. Bu çalışma alanında bir kitle olmayan bir kimlik 404 `audience_not_found`, 50'den fazlası ise 422 verir.
daysint- Pencerenin geriye ne kadar uzandığı; 1 ile 1095 arası. Ne `days:` ne de `minutes:` verilmediğinde 30'dur.
minutesint- Bir günden kısa bir pencere için dakika cinsinden pencere; 1 ile 1576800 arası. İkisi de verildiğinde `days:` değerine üstün gelir.
grainstring- Her dilimin boyutu: `day` (varsayılan), `hour` veya `minute`.
offsetMinutesint- Görüntüleyenin UTC'ye göre dakika cinsinden ofseti; -840 ile 840 arası, böylece gün ve saat aralıkları yerel sınırlarında başlar. Varsayılan olarak 0. `intdiv((int) date('Z'), 60)`, PHP'nin ayarlı olduğu saat diliminin ofsetidir.
Yanıt
sincestring- ISO 8601 UTC; ilk aralığın başlangıcı.
untilstring- ISO 8601 UTC; okumanın yapıldığı an.
totalsarray- `contacts` her kişiyi kaç listede olursa olsun bir kez sayar; `memberships` ise listeleri toplar, bu yüzden bir kişi onu içeren okunan her liste için bir kez sayılır. `added` penceredeki katılımları toplar, `lists` kaç kitlenin okunduğunu gösterir, `busiest` ise en çok katılımın olduğu aralıktır ya da null'dır. `subscribed`, okunan kitlelerden en az birine hâlâ abone olan her kişiyi sayar; `unsubscribed` ise pencere içindeki abonelikten çıkmaları toplar.
seriesarray- Her kitle için bir kayıt; önce en büyükler, sonra ada göre: `id`, `name`, `builtin`, şu anki üye sayısı olan `total`, `subscribed` (hâlâ abone olanlar), `before` (`since` öncesinde katılanlar), `added` (pencere içinde katılanlar), `unsubscribed` (pencere içinde abonelikten çıkanlar) ve en eskiden başlayarak her biri `bucket`, `added` ve `unsubscribed` içeren bir dizi olan `buckets`. Burada `builtin`, bir kitle dizisinin taşıdığı dize değil; varsayılan kitlede `true`, diğerlerinde `false` olur. Yalnızca bir katılım ya da abonelikten çıkma içeren aralıklar listelenir; anahtarları ofsetin yerel saatine göre `YYYY-MM-DD`, `YYYY-MM-DDTHH` ya da `YYYY-MM-DDTHH:MM` biçimindedir.