Python
Listar e obter
`emails.list`, `emails.list_all`, `emails.iterate`, `emails.get` e `emails.list_events`.
emails.list
from openemail import openemail first = openemail.emails.list(status=['queued', 'scheduled'], from_='[email protected]', limit=50) if first['nextCursor']: second = openemail.emails.list( status=['queued', 'scheduled'], from_='[email protected]', limit=50, cursor=first['nextCursor'], )Uma página é {'items': [...], 'hasMore': ..., 'nextCursor': ...}. Passe nextCursor de volta como cursor, com os mesmos filtros, para obter a página seguinte.
emails.iterate e emails.list_all
import sys from openemail import openemail for email in openemail.emails.iterate(status='failed'): print(email['id'], email['lastError'], file=sys.stderr) failures = openemail.emails.list_all(status='failed', from_='[email protected]')Ambos seguem nextCursor por si. iterate é um gerador que só obtém uma página quando o ciclo lá chega, pelo que sair do ciclo interrompe os pedidos, enquanto list_all percorre todas as páginas antes de devolver uma única lista, por isso dê-lhe um filtro que termine. Em ambos os casos a paginação é por keyset, pelo que uma mensagem que chegue a meio da iteração não pode fazer saltar uma linha como aconteceria com um offset.
emails.get e emails.list_events
from openemail import openemail email = openemail.emails.get('msg_…')print(email['status'], email['recipients']) events = openemail.emails.list_all_events('msg_…')for event in events: print(event['type'], event['createdAt'])get é a única chamada que devolve recipients, uma linha por endereço. Uma lista de cinquenta mensagens, cada uma com os seus destinatários, seria uma página de relatório que ninguém pediu.
Parâmetros
statusEmailStatus | Sequence[EmailStatus]- Um estado ou vários (`queued`, `scheduled`, `sending`, `sent`, `partial`, `bounced`, `cancelled`, `failed`), correspondendo a qualquer um dos indicados. O SDK envia uma lista como um único valor separado por vírgulas porque o servidor divide pelas vírgulas; um valor fora desse conjunto dá 422 com o valor desconhecido indicado.
broadcast_idstr- Só as cópias de uma difusão, um id `brd_` vindo de `broadcasts.send`. Cada pessoa que uma difusão alcança recebe uma mensagem própria, por isso isto lista para quem foi e o que aconteceu a cada cópia. `broadcasts.list_recipients` lista as mesmas pessoas com as suas aberturas, cliques e cancelamentos de subscrição.
from_str- Correspondência exata com o endereço de envio tal como foi registado, que é o `addr@host` simples em minúsculas. A linha é escrita sem qualquer nome de apresentação, pelo que um angle-addr como `Acme <[email protected]>` não corresponde a nada. O seu valor é convertido para minúsculas antes da comparação, e é uma igualdade e não uma correspondência por prefixo ou por domínio. O sublinhado final existe porque `from` é uma palavra reservada do Python.
limitint- Linhas nesta página, de 1 a 100, com 25 por predefinição. Um valor fora desse intervalo é recusado com 422 em vez de ser ajustado ao limite.
cursorstr- Um id de mensagem (`msg_…`) a partir do qual paginar. Keyset em vez de offset: as linhas devolvidas são estritamente mais antigas do que o `createdAt` dessa mensagem, pelo que envios que cheguem a meio da página não podem fazer-lhe perder uma linha. Um id que não corresponda a nenhuma mensagem neste espaço de trabalho dá 400.
scheduled_fromdatetime | str- Apenas as mensagens agendadas para este instante ou depois: um `datetime`, ou um instante ISO-8601 com fuso horário. Uma mensagem sem `scheduledAt` fica de fora, por isso com `scheduled_to` e `status=['queued', 'scheduled']` isto lista o que está à espera de sair numa janela de tempo.
scheduled_todatetime | str- Apenas as mensagens agendadas para este instante ou antes. Um `scheduled_from` posterior a ele dá 422 `invalid_parameter` em `scheduledTo`.
Resposta: Page[EmailResource]
itemslist[EmailResource]- Uma página de mensagens, das mais recentes para as mais antigas por `createdAt`, extraída do envelope `data` da API. As linhas da lista nunca incluem a discriminação `recipients` por endereço. Essa está em `get`.
hasMorebool- Indica se há mais linhas que correspondem ao filtro para além desta página. Determinado obtendo uma linha a mais do que `limit`, em vez de uma segunda consulta de contagem.
nextCursorstr | None- O id a passar de volta como `cursor`, e null na última página. `iterate` e `list_all` param quando este é null ou `hasMore` é false, já que uma página que indicasse haver mais sem nomear nenhum cursor ficaria em ciclo infinito.
items[].objectLiteral['email']- Sempre `'email'` numa linha desta lista.
items[].idstr- O id próprio desta API, `msg_…`. É o que todos os outros endpoints de emails recebem e o que um cursor refere.
items[].statusEmailStatus- Em que fase da sua vida está a mensagem. `partial` é um estado próprio e não uma variante de falha: alguns destinatários já a têm e não é possível anular o envio, pelo que tentar de novo é errado. `bounced` significa que foi devolvida por todos os destinatários depois de sair, pelo que ninguém a tem, e cada destinatário em `get` diz porquê.
items[].modeApiKeyMode- `live` ou `test`, retirado da chave que a enviou. Um envio de teste é registado aqui e nunca é transmitido.
items[].fromstr- O endereço com que o envio foi autorizado, guardado simples e em minúsculas, pelo que um nome de apresentação indicado em `from` continua a ser enviado mas não é guardado aqui. Uma string simples e não um dicionário, porque esta é a identidade que foi autorizada: um endereço fora do âmbito de envio de uma chave, que não esteja num domínio que ela detém nem nomeado nela, é recusado com 403, e nunca é trocado silenciosamente por um que esteja.
items[].subjectstr | None- O assunto tal como foi guardado. É null numa mensagem registada sem assunto.
items[].messageIdstr | None- O Message-ID do RFC 5322, e não o nosso id. É null até o MIME existir, e é reescrito pelo serviço de envio à saída, pelo que uma devolução ou DSN posterior traz um id diferente e a correlação faz-se por `items[].id`.
items[].threadIdstr | None- A conversa a que esta mensagem pertence, quando foi indicada ou atribuída. Caso contrário, null.
items[].transportEmailTransport | str | None- Como os bytes saíram. É null até ao despacho, e o tipo é aberto para que um transporte que este SDK ainda não nomeia não seja uma alteração incompatível: os registos guardados podem ainda nomear transportes que já não são usados.
items[].attemptsint- Quantas tentativas de despacho a mensagem teve, 0 antes da primeira.
items[].lastErrorstr | None- O erro de despacho mais recente, escrito para uma pessoa. É null enquanto nada tiver falhado.
items[].scheduledAtstr | None- Quando a mensagem deve sair, como instante ISO-8601. É null apenas num envio imediato sem janela de cancelamento: uma janela é um pequeno atraso e nada mais, pelo que `cancellableForSeconds` também preenche este campo, numa linha cujo `status` é `queued` e não `scheduled`.
items[].cancellableUntilstr | None- O instante em que a mensagem deve sair, com o mesmo valor que `scheduledAt` em qualquer envio diferido e null num que não o foi. É uma marca temporal para mostrar e não o critério que o servidor usa: `cancel` decide com base em `status`, e só interrompe uma mensagem enquanto ainda está `queued` ou `scheduled`.
items[].sentAtstr | None- Quando saiu. É null até o despacho estar concluído, e é por isso que `status`, e não este, é o campo em que basear a lógica.
items[].tagsdict[str, str]- As etiquetas indicadas no envio, devolvidas tal como vieram e nunca interpretadas. Sempre um dicionário (`{}` quando não foram definidas, nunca null), e só devolvidas: esta chamada filtra por `status`, `from_`, `broadcast_id`, `scheduled_from` e `scheduled_to`, por isso uma etiqueta é algo que se lê numa mensagem, não uma forma de a encontrar.
items[].broadcastIdstr | None- A difusão `brd_` de que esta mensagem é uma cópia, ou null para uma mensagem enviada sozinha.
items[].sourceEmailSource | str- Que superfície pediu o envio: `composer`, `api`, `mcp`, `ai`, `oauth` ou `form`. `api` é este cliente com uma chave de API, e `oauth` é este cliente com um token de acesso.
items[].createdAtstr- Quando o registo de envio foi escrito, o que acontece antes do despacho. É o campo pelo qual a lista é ordenada e o campo com que um cursor é comparado.
items[].trackingNotRequired[EmailTrackingSummary]- O resumo de envolvimento, presente apenas numa linha cuja mensagem foi rastreada e ausente nos restantes casos. A ausência é a resposta a "isto foi rastreado?", enquanto `openCount: 0` se leria como "ninguém a abriu".
items[].tracking.opensbool- Indica se esta mensagem saiu com um píxel. O que foi aplicado a esta mensagem, e não o que a definição da conta diz agora.
items[].tracking.clicksbool- Indica se as ligações desta mensagem foram reescritas. É false quando o corpo não tinha ligações a reescrever, já que nesse caso nada foi alterado.
items[].tracking.openedbool- Indica se foi registada alguma abertura contabilizada, derivado de `openCount > 0`.
items[].tracking.clickedbool- Indica se foi registado algum clique contabilizado, derivado de `clickCount > 0`.
items[].tracking.openCountint- Aberturas que se considera terem sido feitas por uma pessoa, somadas em todas as cópias da mensagem. Scanners e proxies de privacidade são registados mas excluídos, e pedidos repetidos num intervalo de trinta segundos contam como um só.
items[].tracking.clickCountint- Cliques contabilizados, somados em todas as cópias. Os duplicados são eliminados por ligação e não por mensagem, porque seguir duas ligações com segundos de diferença são dois atos e não uma repetição.
items[].tracking.firstOpenAtstr | None- A primeira abertura contabilizada entre todas as cópias, e null enquanto não houver nenhuma. Os acessos automáticos nunca a alteram.
items[].translationNotRequired[EmailTranslationResource]- Nunca está presente numa linha de lista: o registo da tradução está no pedido guardado, que uma lista deliberadamente não obtém. A sua ausência aqui não diz nada sobre se a mensagem foi traduzida. Consulte `get`.