連絡先

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: nil)client.contacts.set_audiences("[email protected]", audienceIds: ["aud_4c1b8e2a7d9f05c36b4e8a71"])client.contacts.delete("[email protected]") puts page.items.size, page.has_more?, contact[:source], contact[:lastSeenAt], saved[:source]

list は最近見かけた連絡先から順に返し、一度もメールを送っていない連絡先は最後になります。source が auto なのは、メンバーがアプリのコンポーザーからそのアドレスにメッセージを送ったために行が書き込まれた場合で、誰かが保存したというのとは本質的に異なる主張です。あるアドレスからメールが届いても何も書き込まれず、この API を通じた送信でも書き込まれません。

アドレス帳は一人の人ではなくワークスペースに属するため、どのメンバーが保存した連絡先も、すべてのメンバーとすべてのキーから見える連絡先になります。create は source を manual として書き込み、書き込みと同時に連絡先を既定のオーディエンスに入れます。同じ呼び出しで自分のリストにも加えるには audienceIds にそれらを指定します（audiences:write も必要です）。または後から audiences.add_contact で追加します。これはオーディエンスのページで説明しています。set_audiences は、連絡先がどのリストに入るかを 1 回の呼び出しで正確に指定します。

contacts.list は OpenEmail::Page を返すため、行は page.items にあり、走査は page.has_more? が true の間 page.next_cursor をたどります。list_all はすべての行を 1 つの Array として返し、iterate は 1 行ずつ yield します。get、create、update、save、set_audiences はいずれも 1 件の連絡先を Symbol キーの Hash として返し、同じ行に audiences が加わります。アドレス帳には上限がないため、このルートは、200 件で黙って打ち切られた Array を返すのではなく、ページ分割します。

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

list_people は、アプリの連絡先ページに表示される人を一覧にします：保存済みの連絡先と、メールで見かけたすべてのアドレスで、それぞれ saved、threads、lastAt を持ちます。list は保存済みの連絡先だけです。OpenEmail::PeoplePage を返し、これは items、has_more?、next_cursor に seen を加えたものです。メールで見かけたアドレスは、キーが threads:read も持つ場合にだけ含まれ、含まれたかどうかは page.seen で分かります。sort: は recent、name、threads のいずれかで、OpenEmail::PEOPLE_SORTS がそれらを定義しています。q: は名前、アドレス、メモを検索し、blocked: true はワークスペースのブロックリストがブロックしている人（ドメイン全体のルールを含む）だけを残します。blockedBy はすべての行でそのルールを示します。

page = client.contacts.list_people(sort: "threads", limit: 50) page.items.each do |person|  client.contacts.save(person[:email]) if !person[:saved] && person[:threads].to_i > 5end blocked = client.contacts.list_all_people(blocked: true)puts page.seen, blocked.size

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

client.contacts.save("[email protected]", name: "Grace Hopper") contact = client.contacts.set_photo("[email protected]", File.binread("photo.jpg"), content_type: "image/jpeg")puts contact[:photoUrl] client.contacts.set_photo("[email protected]", Pathname("photo.png")) client.contacts.remove_photo("[email protected]")client.contacts.delete_many(["[email protected]", "[email protected]"])

block(email) はアドレスをワークスペースのブロックリストに載せてそこからのメールを拒否し、プラスタグは取り除きます。unblock(email) はそのアドレスをブロックしているルールをすべて外します。どちらも連絡先ではなくブロックリストを変更するので settings:write が必要で、どちらもアドレスが連絡先である必要はありません。

list_threads(email) は、すべてのフォルダーで、そのアドレスが書いた、またはそのアドレス宛てに書かれたスレッドをページ単位で返し、list_all_threads と iterate_threads はそれらをたどります。activity(email) は連絡先の「アクティビティ」タブの元になる数値を返します：区間ごとの受信数と送信数、あなたの返信を待っているスレッド、双方向それぞれの返信時間の中央値です。どちらも threads:read が必要です。

threads = client.contacts.list_threads("[email protected]", q: "invoice") activity = client.contacts.activity(  "[email protected]",  minutes: 30 * 24 * 60,  grain: "day",  offset_minutes: Time.now.utc_offset / 60) puts threads.items.size, activity.dig(:totals, :waiting)