Contacts

$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 returns the most recently seen contacts first, and contacts that have never been mailed last. source is auto when the row was written because a member sent that address a message from the app composer, which is a materially different claim from somebody having saved it. Mail arriving from an address writes nothing, and neither does a send through this API.

The book belongs to the workspace rather than to one person, so a contact saved by any member is the contact every member and every key sees. create writes source as manual and puts the contact in the default audience as it is written. Name lists of your own in audienceIds to join them in the same call, which also needs audiences:write, or add the contact later with audiences->addContact, which the Audiences page covers. setAudiences says exactly which lists a contact is in, in one call.

contacts->list returns an OpenEmail\Result\Page, so the rows are on $page->items and the walk follows $page->nextCursor while $page->hasMore is true. listAll returns every row as one array, and iterate returns a Generator that yields them one at a time. get, create, update, save and setAudiences each return one contact as an array keyed in camelCase, the same row plus audiences. The address book is unbounded, which is why this route pages rather than returning an array that silently stopped at 200.

setAudiences($email, ['audienceIds' => [...]]) says exactly which audiences one contact is in, in one request. The contact joins every audience listed that it is not in yet and leaves every other one, and the call returns the contact after the change, with its audiences. It needs audiences:write, because it writes memberships rather than the contact, and repeating it changes nothing, so the client retries it after a network failure.

listPeople lists the people the Contacts page in the app shows: the saved contacts and every address seen in mail, each with saved, threads and lastAt. list is the saved contacts alone. It returns an OpenEmail\Result\PeoplePage, which adds seen to items, hasMore and nextCursor. The addresses seen in mail come only when the key also holds threads:read, and $page->seen says whether they did. sort: is recent, name or threads, and OpenEmail\Constants\PeopleSorts names them. q: searches names, addresses and notes, and blocked: true keeps the people the workspace blocklist blocks, whole-domain rules included. blockedBy names the rule on every row.

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), with an optional array of name and notes, is Add to contacts and Keep in contacts: it saves an address that is not a contact yet, keeps one recorded from a send as saved by hand, and brings back a deleted one. delete is Delete: it removes the saved contact and hides the address, so the composer does not record it again, and it takes an address only ever seen in mail too. wasSaved in the array it returns says which it was. deleteMany deletes up to 200 in one call.

$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) puts the address on the workspace blocklist so mail from it is refused, dropping any plus tag, and unblock($email) takes off every rule that blocks it. Both need settings:write, because they change the blocklist rather than the contact, and neither needs the address to be a contact.

listThreads($email) pages through the threads the address wrote or was written to, in every folder, and listAllThreads and iterateThreads walk them. activity($email) returns the numbers behind a contact’s Activity tab: received and sent per bucket, threads waiting on your reply, and the median reply time each way. Both need 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;