PHP

مخاطبان

`contacts->list`، `get`، `create`، `save`، `update`، `setAudiences`، `delete`، `deleteMany`، `listPeople`، `setPhoto`، `removePhoto`، `block`، `unblock`، `listThreads` و `activity`.

همهٔ متدها

usage.php

$page = $client->contacts->list(limit: 100);$contact = $client->contacts->get('[email protected]'); $saved = $client->contacts->create([    'email' => '[email protected]',    'name' => 'Grace Hopper',    'notes' => 'Met at the compiler workshop',]); $client->contacts->update('[email protected]', ['notes' => null]);$client->contacts->setAudiences('[email protected]', ['audienceIds' => ['aud_4c1b8e2a7d9f05c36b4e8a71']]);$client->contacts->delete('[email protected]'); echo count($page), ' ', $page->hasMore ? 'more to come' : 'that is all', PHP_EOL;echo $contact['source'], ' ', $contact['lastSeenAt'] ?? 'never mailed', ' ', $saved['source'], PHP_EOL;

list مخاطبانی را که تازه‌تر دیده شده‌اند اول برمی‌گرداند، و مخاطبانی را که هرگز به آن‌ها ایمیلی نرفته در انتها. source وقتی auto است که ردیف به این دلیل نوشته شده باشد که عضوی از راه کامپوزر برنامه به آن نشانی پیامی فرستاده است، که ادعایی به‌کلی متفاوت با ذخیره کردن آن توسط کسی است. رسیدن ایمیل از یک نشانی چیزی نمی‌نویسد، و ارسال از راه این API هم همین‌طور.

دفترچه به فضای کاری تعلق دارد نه به یک نفر، پس مخاطبی که هر عضوی ذخیره کند همان مخاطبی است که هر عضو و هر کلید می‌بیند. create مقدار source را manual می‌نویسد و مخاطب را همان لحظهٔ نوشتن در گروه مخاطب پیش‌فرض می‌گذارد. فهرست‌های خودتان را در audienceIds نام ببرید تا در همان فراخوانی به آن‌ها بپیوندد، که به audiences:write هم نیاز دارد، یا مخاطب را بعداً با audiences->addContact اضافه کنید، که صفحهٔ «گروه‌های مخاطب» پوشش می‌دهد. setAudiences با یک فراخوانی دقیقاً می‌گوید یک مخاطب در کدام فهرست‌ها باشد.

نشانی‌ها با حروف کوچک ذخیره می‌شوند و کلاینت نشانی‌ای را که می‌دهید encode می‌کند، پس [email protected] به ردیف درست می‌رسد. نشانی خالی پیش از فرستادن هر چیزی InvalidArgumentException را پرتاب می‌کند. نشانی همان هویت است، پس update نمی‌تواند آن را تغییر دهد: جابه‌جا کردن یک مخاطب یعنی یک delete و یک create.

پارامترها: contacts->list

limitint: در هر صفحه چند مخاطب برگردد: عددی صحیح از 1 تا 200 با پیش‌فرض 50. مقدار بیرون از این بازه به‌جای محدود شدن، یک 422 است. نوع آرگومان `int` است، پس مقداری را که از یک query string خوانده‌اید اول با `(int)` تبدیل کنید.
cursorstring: مقدار `nextCursor` از صفحهٔ پیشین. هرگز خودتان یکی نسازید: cursorی که مخاطبی را نام ببرد که دیگر وجود ندارد یک 400 `invalid_cursor` است که به‌صورت `InvalidRequestException` پرتاب می‌شود، یعنی وضعیت صفحه‌بندی شما کهنه است و پیمایش باید بدون cursor از نو آغاز شود.
sourcestring: `manual` برای مخاطبانی که کسی عمداً ذخیره کرده، و `auto` برای آن‌هایی که کامپوزر برنامه ثبت کرده است. برای کل دفترچه آن را ننویسید.
qstring: در نام و نشانی جست‌وجو می‌کند، تا ۲۰۰ نویسه. اگر در صفحهٔ نخست هیچ چیز دقیقاً جور نشود، به‌جایش نوشتارهای نزدیک برگردانده می‌شوند، و صفحه‌های بعدی به همان شیوه جست‌وجو را ادامه می‌دهند.

پاسخ: یک مخاطب

contacts->list یک OpenEmail\Result\Page برمی‌گرداند، پس ردیف‌ها روی $page->items هستند و پیمایش تا وقتی $page->hasMore برابر true است $page->nextCursor را دنبال می‌کند. listAll همهٔ ردیف‌ها را به‌صورت یک آرایه برمی‌گرداند، و iterate یک Generator برمی‌گرداند که آن‌ها را یکی‌یکی yield می‌کند. get، create، update، save و setAudiences هرکدام یک مخاطب را به‌صورت یک آرایه با کلیدهای camelCase برمی‌گردانند، همان ردیف به‌علاوهٔ audiences. دفترچهٔ نشانی‌ها بی‌کران است، و به همین دلیل این مسیر صفحه‌بندی می‌کند به‌جای آنکه آرایه‌ای برگرداند که بی‌صدا در 200 متوقف شده باشد.

objectstring: همیشه رشتهٔ `contact`، هم روی ردیف‌های فهرست و هم روی `get`.
emailstring: آدرس، که هنگام نوشتن با حروف کوچک ذخیره می‌شود تا `[email protected]` و `[email protected]` یک مخاطب باشند، و همان کلیدی که هر متد contacts می‌گیرد، چون هیچ id ای برای مخاطب آشکار نمی‌شود. ردیف‌ها به فضای کاری تعلق دارند نه به عضو یا کلیدی که آن‌ها را نوشته، پس هر عضو و هر کلید روی فضای کاری یک دفترچهٔ نشانی واحد را می‌خواند و می‌نویسد.
namestring or null: نام نمایشی، یا null وقتی هرگز نامی برای آن نشانی ثبت نشده باشد. نوشتن خودکار تنها وقتی نامی دارد که سرآیند چیزی جز خودِ نشانی داده باشد، و هرگز نمی‌تواند نامی را که کاربر تایپ کرده بازنویسی کند.
sourcestring: `auto` یعنی ردیف به این دلیل نوشته شده که کاربر به آن نشانی ایمیل فرستاده است. `manual` یعنی کسی آن را دستی وارد کرده، که ادعایی به‌کلی متفاوت است، و یک upsert هرگز `manual` را به `auto` تنزل نمی‌دهد. رسیدن ایمیل از یک نشانی عمداً هیچ ردیفی نمی‌نویسد، پس کسی که فقط به شما نوشته اینجا نیست. با این مقدار مانند یک رشتهٔ باز رفتار کنید، چون این ستون متن آزاد با پیش‌فرض `manual` است.
notesstring or null: متن آزادی که کسی دربارهٔ این شخص نوشته، در برنامه یا از راه `update`، و هرگز تولیدشده نیست. وقتی کسی چیزی ننوشته باشد null است، و `'notes' => null` در `update` آن را پاک می‌کند.
lastSeenAtstring or null: یک رشته با قالب ISO 8601 به وقت UTC، که هر بار عضوی از کامپوزر برنامه به آن نشانی ارسال کند جلو می‌رود، نه وقتی ایمیلی از آن می‌رسد، که چیزی نمی‌نویسد. روی مخاطبی که با `create` ذخیره شده و هرگز به او ایمیلی نرفته null است، و این‌ها در ترتیب نزولی `lastSeenAt` که این مسیر برمی‌گرداند در انتها می‌آیند.
audiencesarray: فقط روی `get`، `create`، `update`، `save` و `setAudiences`، و هرگز روی ردیف‌های فهرست. هر گروه مخاطبی که مخاطب در آن است، از جمله گروه پیش‌فرض، به‌صورت یک آرایه با `id`، `name` و `builtin`. `builtin` روی گروهی که هر مخاطبی به آن تعلق دارد `default` است و روی گروهی که کسی ساخته null، پس به‌جای نام، که هرکسی می‌تواند عوضش کند، روی آن شاخه بزنید.
photoUrlstring or null: جایی که عکس مخاطب از آن ارائه می‌شود، یا null وقتی مخاطب عکسی ندارد. `setPhoto` آن را می‌گذارد و هر بارگذاری URL تازه‌ای می‌گیرد.

تنظیم گروه‌های مخاطبِ یک مخاطب

setAudiences($email, ['audienceIds' => [...]]) با یک درخواست دقیقاً می‌گوید یک مخاطب در کدام گروه‌ها باشد. مخاطب به هر گروه فهرست‌شده‌ای که هنوز در آن نیست می‌پیوندد و هر گروه دیگری را ترک می‌کند، و فراخوانی مخاطب را پس از تغییر، همراه با audiences آن، برمی‌گرداند. به audiences:write نیاز دارد، چون عضویت‌ها را می‌نویسد نه خود مخاطب را، و تکرارش چیزی را تغییر نمی‌دهد، پس کلاینت پس از شکست شبکه دوباره امتحانش می‌کند.

گروه مخاطب پیش‌فرض همیشه نگه داشته می‌شود، پس 'audienceIds' => [] مخاطب را تنها در گروه پیش‌فرض باقی می‌گذارد. تا 100 شناسه می‌پذیرد. شناسه‌ای که به هیچ گروه مخاطبی در این فضای کاری اشاره نکند یک 404 audience_not_found است و هیچ چیز تغییر نمی‌کند، و نشانی‌ای که مخاطب نیست یک 404 contact_not_found است. هر دو NotFoundException را پرتاب می‌کنند.

همهٔ کسانی که در صفحهٔ مخاطبین هستند

listPeople کسانی را فهرست می‌کند که صفحهٔ «مخاطبان» در برنامه نشان می‌دهد: مخاطبان ذخیره‌شده و هر نشانی دیده‌شده در ایمیل‌ها، هرکدام با saved، threads و lastAt. list فقط مخاطبان ذخیره‌شده است. یک OpenEmail\Result\PeoplePage برمی‌گرداند، که seen را به items، hasMore و nextCursor می‌افزاید. نشانی‌های دیده‌شده در ایمیل‌ها فقط وقتی می‌آیند که کلید threads:read را هم داشته باشد، و $page->seen می‌گوید آمده‌اند یا نه. sort: یکی از recent، name یا threads است، و OpenEmail\Constants\PeopleSorts آن‌ها را نام می‌برد. q: در نام‌ها، نشانی‌ها و یادداشت‌ها جست‌وجو می‌کند، و blocked: true کسانی را نگه می‌دارد که فهرست مسدودی فضای کاری مسدودشان کرده، از جمله قواعد کل دامنه. blockedBy در هر ردیف قاعده را نام می‌برد.

people.php

use OpenEmail\Constants\PeopleSorts; $page = $client->contacts->listPeople(sort: PeopleSorts::THREADS, limit: 50); foreach ($page as $person) {    if (!$person['saved'] && $person['threads'] > 5) {        $client->contacts->save($person['email']);    }} $blocked = $client->contacts->listAllPeople(blocked: true);echo $page->seen ? 'saved and seen' : 'saved only', ', ', count($blocked), ' blocked', PHP_EOL;

listAllPeople همهٔ صفحه‌ها را به‌صورت یک آرایه برمی‌گرداند، و iteratePeople یک Generator برمی‌گرداند که هر شخص را yield می‌کند. هیچ‌کدام seen را گزارش نمی‌کنند، پس برای دانستنش یک صفحه را با listPeople بخوانید. cursor مبهم است، پس nextCursor را دقیقاً همان‌طور که آمده، با همان sort:، q: و blocked:، به‌عنوان cursor: پس بدهید.

ذخیره، حذف و عکس‌ها

save($email)، با آرایه‌ای اختیاری از name و notes، همان «افزودن به مخاطبان» و «نگه داشتن در مخاطبان» است: نشانی‌ای را که هنوز مخاطب نیست ذخیره می‌کند، نشانی ثبت‌شده از یک ارسال را به‌عنوان ذخیره‌شدهٔ دستی نگه می‌دارد، و نشانی حذف‌شده را برمی‌گرداند. delete همان «حذف» است: مخاطب ذخیره‌شده را برمی‌دارد و نشانی را پنهان می‌کند تا کامپوزر دوباره ثبتش نکند، و نشانی‌ای را هم که فقط در ایمیل‌ها دیده شده می‌پذیرد. wasSaved در آرایه‌ای که برمی‌گرداند می‌گوید کدام بوده است. deleteMany در یک فراخوانی تا 200 مورد را حذف می‌کند.

photo.php

$client->contacts->save('[email protected]', ['name' => 'Grace Hopper']); $contact = $client->contacts->setPhoto('[email protected]', file_get_contents('photo.jpg'), contentType: 'image/jpeg');echo $contact['photoUrl'], PHP_EOL; $client->contacts->setPhoto('[email protected]', new \SplFileInfo('avatar.png')); $client->contacts->removePhoto('[email protected]');$client->contacts->deleteMany(['[email protected]', '[email protected]']);

setPhoto بایت‌های تصویر را همان‌طور که هستند می‌فرستد: PNG، JPEG، WebP یا GIF تا 5 MB، که در مربعی 512 پیکسلی جا داده می‌شود. بایت‌ها یک رشته، یک منبع stream از fopen، یک SplFileInfo، یا یک stream یا فایل بارگذاری‌شدهٔ PSR-7 هستند. contentType: را بدهید، یا بایت‌هایی که نوع خودشان را همراه دارند: یک فایل بارگذاری‌شدهٔ PSR-7، یا یک بارگذاری Symfony یا Laravel، همراه با نوع رسانه‌اش، یا فایل یا streamی که نامش به .png، .jpg، .jpeg، .webp یا .gif ختم شود. بدون نوع، بایت‌ها به‌صورت application/octet-stream می‌روند، که سرور آن را با یک 422 invalid_image رد می‌کند. OpenEmail\Constants\ContactPhotoTypes این چهار نوع را نام می‌برد. نشانی باید پیش از آن مخاطب ذخیره‌شده باشد.

مسدود کردن

block($email) نشانی را در فهرست مسدودی فضای کاری می‌گذارد تا نامه‌اش رد شود و هر برچسب بعلاوه را کنار می‌گذارد، و unblock($email) هر قاعده‌ای را که مسدودش می‌کند برمی‌دارد. هر دو به settings:write نیاز دارند، چون فهرست مسدودی را تغییر می‌دهند نه مخاطب را، و هیچ‌کدام لازم ندارند نشانی مخاطب باشد.

وقتی unblock قاعدهٔ کل دامنه‌ای را برمی‌دارد، removed آن را با list برابر blockedDomains فهرست می‌کند، و مسدودیت همهٔ کسانی که در آن دامنه‌اند همراه آن برداشته می‌شود. OpenEmail\Constants\ContactBlockLists هر دو فهرست را نام می‌برد.

گفت‌وگوها و فعالیت

listThreads($email) رشته‌هایی را که نشانی نوشته یا به آن نوشته شده، در همهٔ پوشه‌ها، صفحه به صفحه مرور می‌کند، و listAllThreads و iterateThreads همه را می‌پیمایند. activity($email) عددهای پشت زبانهٔ «فعالیت» یک مخاطب را برمی‌گرداند: دریافتی و ارسالی در هر بازه، رشته‌هایی که منتظر پاسخ شما هستند، و میانهٔ زمان پاسخ در هر دو سو. هر دو به threads:read نیاز دارند.

activity.php

$threads = $client->contacts->listThreads('[email protected]', q: 'invoice'); $activity = $client->contacts->activity(    '[email protected]',    minutes: 30 * 24 * 60,    grain: 'day',    offsetMinutes: intdiv((int) date('Z'), 60),); echo count($threads), ' threads, ', $activity['totals']['waiting'], ' waiting on you', PHP_EOL;

activity آرگومان‌های نام‌دار می‌گیرد. minutes: پنجره را تعیین می‌کند، که اگر داده نشود 90 روز است. grain: پهنای هر بازه را تعیین می‌کند: minute، hour یا day. offsetMinutes: تعداد دقیقه‌های شرق UTC را تعیین می‌کند که مرز روزها بر اساس آن است، و intdiv((int) date('Z'), 60) همان offset منطقهٔ زمانی‌ای است که PHP روی آن تنظیم شده.