Contacts

from openemail import openemail page = openemail.contacts.list(limit=100)contact = openemail.contacts.get('[email protected]') saved = openemail.contacts.create({    'email': '[email protected]',    'name': 'Grace Hopper',    'notes': 'Met at the compiler workshop',}) openemail.contacts.update(saved['email'], {'notes': None})openemail.contacts.set_audiences(saved['email'], {    'audienceIds': ['aud_4c1b8e2a7d9f05c36b4e8a71'],})openemail.contacts.delete(saved['email']) print(len(page['items']), page['hasMore'], contact['source'], contact['lastSeenAt'])

Most recently seen first, with 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 openemail.audiences.add_contact. set_audiences says exactly which lists a contact is in, in one call.

contacts.list returns a Page[ContactResource], so the rows are on page['items'] and the walk follows page['nextCursor'] while page['hasMore'] is True, which list_all and iterate do for you. get, create, save, update, set_audiences, set_photo and remove_photo each return one ContactDetailResource, the same row plus audiences. The address book is unbounded, which is why this route pages rather than returning a list that silently stopped at 200.

set_audiences(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 ContactDetailResource after the change. It needs audiences:write, because it writes memberships rather than the contact, and repeating it changes nothing.

list_people 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. 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, 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.

from openemail import openemail page = openemail.contacts.list_people(sort='threads', limit=50) for person in page['items']:    if not person['saved'] and (person['threads'] or 0) > 5:        openemail.contacts.save(person['email']) blocked = openemail.contacts.list_all_people(blocked=True)

save(email, {'name': ..., '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 says which it was. delete_many deletes up to 200 in one call.

from pathlib import Path from openemail import openemail openemail.contacts.save('[email protected]', {'name': 'Grace Hopper'}) photo = Path('grace.jpg').read_bytes()contact = openemail.contacts.set_photo('[email protected]', photo, content_type='image/jpeg') openemail.contacts.remove_photo('[email protected]')openemail.contacts.delete_many(['[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.

list_threads(email) pages through the threads the address wrote or was written to, in every folder, and list_all_threads and iterate_threads 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.

import time from openemail import openemail threads = openemail.contacts.list_threads('[email protected]', q='invoice') activity = openemail.contacts.activity(    '[email protected]',    minutes=30 * 24 * 60,    grain='day',    offset_minutes=time.localtime().tm_gmtoff // 60,) print(len(threads['items']), activity['totals']['waiting'])

• contacts.list()Full reference
• contacts.list_all()Full reference
• contacts.iterate()Full reference
• contacts.get()Full reference
• contacts.create()Full reference
• contacts.save()Full reference
• contacts.update()Full reference
• contacts.set_audiences()Full reference
• contacts.delete()Full reference
• contacts.delete_many()Full reference
• contacts.list_people()Full reference
• contacts.list_all_people()Full reference
• contacts.iterate_people()Full reference
• contacts.set_photo()Full reference
• contacts.remove_photo()Full reference
• contacts.block()Full reference
• contacts.unblock()Full reference
• contacts.list_threads()Full reference
• contacts.list_all_threads()Full reference
• contacts.iterate_threads()Full reference
• contacts.activity()Full reference