連絡先

$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 は、連絡先がどのリストに入るかを 1 回の呼び出しで正確に指定します。

contacts->list は OpenEmail\Result\Page を返すため、行は $page->items にあり、走査は $page->hasMore が true の間 $page->nextCursor をたどります。listAll はすべての行を 1 つの配列として返し、iterate は 1 行ずつ yield する Generator を返します。get、create、update、save、setAudiences はいずれも 1 件の連絡先を camelCase のキーを持つ配列として返し、同じ行に audiences が加わります。アドレス帳には上限がないため、このルートは、200 件で黙って打ち切られた配列を返すのではなく、ページ分割します。

setAudiences($email, ['audienceIds' => [...]]) は、1 件の連絡先がどのオーディエンスに入るかを 1 回のリクエストで正確に指定します。連絡先は、指定されたオーディエンスのうちまだ入っていないものすべてに加わり、それ以外のすべてから抜けます。呼び出しは変更後の連絡先を audiences 付きで返します。連絡先ではなくメンバーシップを書き込むため audiences:write が必要で、繰り返しても何も変わらないため、クライアントはネットワーク障害の後にリトライします。

listPeople は、アプリの連絡先ページに表示される人を一覧にします：保存済みの連絡先と、メールで見かけたすべてのアドレスで、それぞれ saved、threads、lastAt を持ちます。list は保存済みの連絡先だけです。OpenEmail\Result\PeoplePage を返し、これは items、hasMore、nextCursor に seen を加えたものです。メールで見かけたアドレスは、キーが 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;

name と notes を持つ省略可能な配列を付けた save($email) は、アプリの「連絡先に追加」と「連絡先に残す」にあたります。まだ連絡先でないアドレスを保存し、送信から記録された連絡先を手で保存したものとして残し、削除された連絡先を復活させます。delete は「削除」にあたります。保存済みの連絡先を削除してアドレスを非表示にするため、コンポーザーがそれを再び記録することはありません。メールで見かけただけのアドレスも受け付けます。返される配列の wasSaved が、どちらだったかを示します。deleteMany は 1 回の呼び出しで最大 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;