Контакты

$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 одним вызовом точно задаёт, в каких списках состоит контакт.

contacts->list возвращает OpenEmail\Result\Page, поэтому строки лежат в $page->items, а обход идёт по $page->nextCursor, пока $page->hasMore истинно. listAll возвращает все строки одним массивом, а iterate возвращает Generator, который выдаёт их по одной. get, create, update, save и setAudiences возвращают по одному контакту как массив с ключами в camelCase: та же строка плюс audiences. Адресная книга не ограничена по размеру, поэтому этот маршрут отдаёт данные постранично, а не возвращает массив, который молча обрывается на 200.

setAudiences($email, ['audienceIds' => [...]]) одним запросом точно задаёт, в каких аудиториях состоит один контакт. Контакт вступает во все перечисленные аудитории, в которых ещё не состоит, и выходит из всех остальных, а вызов возвращает контакт после изменения вместе с его audiences. Ему нужна audiences:write, потому что он записывает членство, а не сам контакт, и повтор ничего не меняет, поэтому клиент повторяет его после сетевого сбоя.

listPeople перечисляет людей, которых показывает страница «Контакты» в приложении: сохранённые контакты и каждый адрес из почты, у каждого saved, threads и lastAt, и возвращает OpenEmail\Result\PeoplePage, которая добавляет seen к items, hasMore и nextCursor. list возвращает только сохранённые контакты. Адреса из почты приходят, только если у ключа есть ещё и threads:read, а $page->seen сообщает, пришли ли они. sort: принимает recent, name или threads, и OpenEmail\Constants\PeopleSorts их перечисляет. q: ищет по именам, адресам и заметкам, а blocked: true оставляет людей, которых блокирует список блокировки рабочего пространства, включая правила на целый домен. blockedBy называет правило в каждой строке.

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;

save($email) с необязательным массивом из name и notes соответствует действиям «Добавить в контакты» и «Оставить в контактах»: сохраняет адрес, который ещё не является контактом, оставляет записанный при отправке как сохранённый вручную и возвращает удалённый. delete соответствует действию «Удалить»: убирает сохранённый контакт и скрывает адрес, чтобы композер не записал его снова, и принимает также адрес, который встречался только в почте. wasSaved в возвращаемом массиве сообщает, какой это был случай. deleteMany удаляет до 200 за один вызов.

$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]']);

block($email) вносит адрес в список блокировки рабочего пространства, чтобы письма с него отклонялись, отбрасывая плюс-метку, а unblock($email) снимает каждое правило, которое его блокирует. Обоим нужен settings:write, потому что они меняют список блокировки, а не контакт, и ни одному не нужно, чтобы адрес был контактом.

listThreads($email) постранично перебирает цепочки во всех папках, в которых этот адрес писал или ему писали, а listAllThreads и iterateThreads обходят их. activity($email) возвращает числа, стоящие за вкладкой «Активность» контакта: полученные и отправленные по интервалам, цепочки, ждущие вашего ответа, и медианное время ответа в каждую сторону. Обоим нужна threads:read.

$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;