Contactos
`contacts.list`, `get`, `create`, `save`, `update`, `set_audiences`, `delete`, `delete_many`, `list_people`, `set_photo`, `remove_photo`, `block`, `unblock`, `list_threads` e `activity`.
Todos os métodos
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'])Os vistos mais recentemente primeiro, com os contactos que nunca receberam email no fim. source é auto quando a linha foi escrita porque um membro enviou uma mensagem para esse endereço a partir do editor de mensagens da aplicação, o que é uma afirmação materialmente diferente de alguém o ter guardado. O correio recebido de um endereço não escreve nada, e um envio através desta API também não.
O livro de endereços pertence ao espaço de trabalho e não a uma pessoa, pelo que um contacto guardado por qualquer membro é o contacto que todos os membros e todas as chaves veem. create escreve source como manual e coloca o contacto na audiência predefinida no momento da escrita. Indique listas suas em audienceIds para o associar a elas na mesma chamada, o que também exige audiences:write, ou adicione o contacto mais tarde com openemail.audiences.add_contact. set_audiences diz exatamente em que listas está um contacto, numa só chamada.
Os endereços são guardados em minúsculas e o cliente codifica o que passar, pelo que [email protected] chega à linha certa. O endereço é a identidade, pelo que update não o pode alterar: mudar um contacto de endereço é um delete seguido de um create.
Parâmetros: contacts.list
limitint- Quantos contactos devolver por página: um inteiro de 1 a 200, com 50 por predefinição. O valor é convertido, pelo que `'100'` vindo de uma query string é aceite, e um valor fora do intervalo dá 422 em vez de ser ajustado ao limite.
cursorstr- O `nextCursor` da página anterior. Nunca construa um manualmente: um cursor que refere um contacto que já não existe dá 400 `invalid_cursor`, o que significa que o seu estado de paginação está desatualizado e o percurso deve recomeçar sem cursor.
sourceContactSource- `'manual'` para os contactos que alguém guardou intencionalmente, `'auto'` para os que o editor de mensagens da aplicação registou. Omita-o para obter todo o livro de endereços.
qstr- Pesquisa o nome e o endereço, até 200 caracteres. Quando nada coincide exatamente na primeira página, são devolvidas grafias próximas, e as páginas seguintes continuam a pesquisar da mesma forma.
Resposta: ContactResource
contacts.list devolve um Page[ContactResource], pelo que as linhas estão em page['items'] e o percurso segue page['nextCursor'] enquanto page['hasMore'] for True, o que list_all e iterate fazem por si. get, create, save, update, set_audiences, set_photo e remove_photo devolvem cada um um ContactDetailResource, a mesma linha mais audiences. O livro de endereços não tem limite, e é por isso que esta rota pagina em vez de devolver uma lista que parava silenciosamente nas 200 linhas.
objectLiteral['contact']- Sempre a string `contact`, tanto nas linhas da lista como em `get`.
emailstr- O endereço, convertido para minúsculas na escrita para que `[email protected]` e `[email protected]` sejam um só contacto, e o identificador que todos os métodos de contactos recebem, já que nenhum id de contacto é exposto. As linhas pertencem ao espaço de trabalho e não ao membro ou à chave que as escreveu, pelo que todos os membros e todas as chaves do espaço de trabalho leem e escrevem um único livro de endereços.
namestr | None- `None` quando nunca foi registado nenhum nome para o endereço. Uma escrita automática só inclui um quando o cabeçalho forneceu algo diferente do próprio endereço, e nunca pode substituir um nome que o utilizador escreveu.
sourceContactSource | str- `auto` significa que a linha foi escrita porque o utilizador enviou correio para esse endereço; `manual` significa que alguém o introduziu à mão, uma afirmação materialmente diferente, e um upsert nunca rebaixa `manual` para `auto`. O correio recebido de um endereço não escreve nenhuma linha, de propósito, pelo que alguém que apenas lhe escreveu não está aqui; a união permanece aberta porque a coluna é texto livre com `manual` como predefinição.
notesstr | None- Texto livre que alguém escreveu sobre esta pessoa, na aplicação ou através de `update`, nunca gerado. É `None` quando ninguém escreveu nada, e um `None` explícito em `update` limpa-o.
lastSeenAtstr | None- ISO-8601 UTC, atualizado sempre que um membro envia para esse endereço a partir do editor de mensagens da aplicação, e não quando chega correio dele, o que não escreve nada. É `None` num contacto guardado através de `create` que nunca recebeu email, e esses ficam em último lugar na ordem descendente por `lastSeenAt` que esta rota devolve.
audienceslist[ContactAudienceResource]- Só em `get`, `create`, `save`, `update`, `set_audiences`, `set_photo` e `remove_photo`, nunca nas linhas da lista. Todas as audiências a que o contacto pertence, como um dicionário com `id`, `name` e `builtin`, incluindo a predefinida. `builtin` é `default` na audiência a que todos os contactos pertencem e `None` numa criada por alguém, por isso baseie a lógica nele e não no nome, que qualquer pessoa pode alterar.
photoUrlstr | None- Onde a foto do contacto é servida, ou `None` quando o contacto não tem nenhuma. `set_photo` define-a e cada carregamento recebe um URL novo.
Definir as audiências de um contacto
set_audiences(email, {'audienceIds': [...]}) diz exatamente em que audiências está um contacto, num só pedido. O contacto entra em cada audiência indicada onde ainda não está e sai de todas as outras, e a chamada devolve o ContactDetailResource depois da alteração. Requer audiences:write, porque escreve pertenças e não o contacto, e repeti-la não muda nada.
A audiência predefinida é sempre mantida, pelo que {'audienceIds': []} deixa o contacto apenas na audiência predefinida. Aceita até 100 ids. Um id que não designa nenhuma audiência deste espaço de trabalho dá um 404 audience_not_found e nada muda, e um endereço que não é contacto dá um 404 contact_not_found.
Todos os que estão na página de Contactos
list_people lista as pessoas que a página de Contactos da app mostra: os contactos guardados e cada endereço visto no correio, cada um com saved, threads e lastAt. list são só os contactos guardados. Os endereços vistos no correio só vêm quando a chave também tem threads:read, e page['seen'] diz se vieram. sort é recent, name ou threads, q pesquisa nomes, endereços e notas, e blocked=True fica com as pessoas que a lista de bloqueio do espaço de trabalho bloqueia, incluindo regras de domínio inteiro. blockedBy indica a regra em cada linha.
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)list_all_people e iterate_people percorrem todas as páginas. O cursor é opaco, por isso devolva nextCursor tal como veio, com os mesmos sort, q e blocked.
Guardar, eliminar e fotos
save(email, {'name': ..., 'notes': ...}) é Adicionar aos contactos e Manter nos contactos: guarda um endereço que ainda não é contacto, mantém como guardado à mão um registado a partir de um envio e traz de volta um eliminado. delete é Eliminar: tira o contacto guardado e oculta o endereço, para que o editor não o volte a registar, e aceita também um endereço só visto no correio. wasSaved diz qual dos casos era. delete_many elimina até 200 numa só chamada.
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]'])set_photo envia os bytes da imagem tal como estão: PNG, JPEG, WebP ou GIF até 5 MB, ajustados a um quadrado de 512 píxeis. Passe content_type=, porque os bytes não trazem um tipo próprio: sem ele, o carregamento segue como application/octet-stream, que é recusado com 422 invalid_image. O endereço tem de ser primeiro um contacto guardado.
Bloqueio
block(email) põe o endereço na lista de bloqueio do espaço de trabalho para que o correio dele seja recusado, descartando qualquer etiqueta com mais, e unblock(email) tira cada regra que o bloqueia. Ambos precisam de settings:write, porque alteram a lista de bloqueio e não o contacto, e nenhum precisa que o endereço seja um contacto.
Quando unblock levanta uma regra de domínio inteiro, removed lista-a com list em blockedDomains, e todos nesse domínio ficam desbloqueados com ela.
Conversas e atividade
list_threads(email) percorre por páginas as conversas que o endereço escreveu ou em que lhe escreveram, em todas as pastas, e list_all_threads e iterate_threads percorrem-nas todas. activity(email) devolve os números por trás do separador Atividade de um contacto: recebidos e enviados por intervalo, conversas à espera da sua resposta e o tempo mediano de resposta em cada sentido. Ambos precisam de 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'])Referência
contacts.list()Referência completacontacts.list_all()Referência completacontacts.iterate()Referência completacontacts.get()Referência completacontacts.create()Referência completacontacts.save()Referência completacontacts.update()Referência completacontacts.set_audiences()Referência completacontacts.delete()Referência completacontacts.delete_many()Referência completacontacts.list_people()Referência completacontacts.list_all_people()Referência completacontacts.iterate_people()Referência completacontacts.set_photo()Referência completacontacts.remove_photo()Referência completacontacts.block()Referência completacontacts.unblock()Referência completacontacts.list_threads()Referência completacontacts.list_all_threads()Referência completacontacts.iterate_threads()Referência completacontacts.activity()Referência completa