Ruby

Listar e obter

`emails.list`, `emails.list_all`, `emails.iterate`, `emails.get` e `emails.list_events`.

emails.list

list_emails.rb

filters = {status: ["queued", "scheduled"], from: "[email protected]"} first = client.emails.list(**filters, limit: 50)second = client.emails.list(**filters, limit: 50, cursor: first.next_cursor) if first.next_cursor p first.items.size, second&.items&.size

Uma página é uma OpenEmail::Page com items, has_more? e next_cursor. Passe next_cursor de volta como cursor:, com os mesmos filtros, para obter a página seguinte.

emails.iterate e emails.list_all

iterate_emails.rb

client.emails.iterate(status: "failed") do |email|  warn "#{email[:id]} #{email[:lastError]}"end failures = client.emails.list_all(status: "failed", from: "[email protected]")puts failures.size

Ambos seguem next_cursor por si. iterate só obtém uma página quando o percurso lá chega, pelo que break no bloco, ou first ou find sobre o Enumerator que devolve sem bloco, interrompem os pedidos, enquanto list_all percorre todas as páginas antes de devolver um único Array, 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

get_email.rb

email = client.emails.get("msg_3f9a1c07d2b84e6a9c5b1f20")puts email[:status]p email[:recipients] events = client.emails.list_all_events("msg_3f9a1c07d2b84e6a9c5b1f20")events.each { |event| puts "#{event[:type]} #{event[:createdAt]}" }

get é a única chamada que devolve recipients, um Hash por endereço com os seus próprios status, error e deliveredAt. Uma lista de cinquenta mensagens, cada uma com os seus destinatários, seria uma página de relatório que ninguém pediu.

list_events lê o histórico de eventos de um envio, do mais antigo para o mais recente: email.accepted, email.queued, email.sent, email.delivered, email.bounced, email.opened e os restantes, cada um com um Hash data cuja forma depende do seu type. list_all_events e iterate_events percorrem todo o histórico por si. Os webhooks entregam um subconjunto desses mesmos eventos à medida que acontecem, por isso é aqui que deve procurar quando falhou um webhook.

Parâmetros

statusString or Array<String>: Um estado ou vários (`queued`, `scheduled`, `sending`, `sent`, `partial`, `bounced`, `cancelled`, `failed`), correspondendo a qualquer um dos indicados. `bounced` significa que todos os destinatários a quem a mensagem foi enviada a devolveram, enquanto uma mensagem devolvida por alguns e que chegou aos restantes aparece como `partial`. A gem envia um Array como um único valor separado por vírgulas porque o servidor divide pelas vírgulas, e um valor fora desse conjunto dá 422 com o valor desconhecido indicado.
broadcast_idString: 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.
fromString: 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.
scheduled_fromTime, DateTime or String: Apenas as mensagens agendadas para este instante ou depois. Com `scheduled_to:` e `status: ["scheduled", "queued"]` lista o que está à espera de sair numa janela de tempo, como faz o calendário da aplicação. Uma mensagem sem `scheduledAt` fica de fora. Passe um Time, um DateTime ou um instante ISO 8601 com o seu fuso: uma Date do Ruby é enviada como data simples, que estes dois filtros recusam.
scheduled_toTime, DateTime or String: Apenas as mensagens agendadas para este instante ou antes. Um `scheduled_from:` posterior a `scheduled_to:` dá 422 `invalid_parameter`.
limitInteger: 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. Em `list_all` e `iterate` é o tamanho de cada página que obtêm.
cursorString: 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 `invalid_cursor`.
api_keyString: Lista com esta chave em vez da do cliente.

Uma chave restringida a alguns endereços só lê as mensagens enviadas a partir dos endereços que cobre, e a página é cortada depois desse filtro, por isso todas as páginas exceto a última continuam a ter limit linhas. Um from: que a chave não cobre devolve uma última página vazia em vez de um 403.

Resposta: OpenEmail::Page

itemsArray<Hash>: 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`.
has_more?Boolean: 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.
next_cursorString or nil: O id a passar de volta como `cursor:`, e nil na última página. `iterate` e `list_all` param quando este é nil ou `has_more?` é false, já que uma página que indicasse haver mais sem nomear nenhum cursor ficaria em ciclo infinito.

Cada item

objectString: Sempre `email` numa linha desta lista.
idString: O id próprio desta API, `msg_…`. É o que todas as outras chamadas de emails recebem e o que um cursor refere.
statusString: 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ê.
modeString: `live` ou `test`, retirado da chave que a enviou. Um envio de teste é registado aqui e nunca é transmitido.
fromString: 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 Hash, 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.
subjectString or nil: O assunto tal como foi guardado. É nil numa mensagem registada sem assunto.
messageIdString or nil: O Message-ID do RFC 5322, e não o nosso id. É nil 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 `id`.
threadIdString or nil: A conversa a que esta mensagem pertence, quando foi indicada ou atribuída. Caso contrário, nil.
transportString or nil: Como os bytes saíram. É nil até ao despacho. Os registos guardados ainda podem nomear transportes que já não são usados, por isso trate um valor que não conheça como informação e não como um erro.
attemptsInteger: Quantas tentativas de despacho a mensagem teve, 0 antes da primeira.
lastErrorString or nil: O erro de despacho mais recente, escrito para uma pessoa. É nil enquanto nada tiver falhado.
scheduledAtString or nil: Quando a mensagem deve sair, como instante ISO 8601. É nil 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`.
cancellableUntilString or nil: O instante em que a mensagem deve sair, com o mesmo valor que `scheduledAt` em qualquer envio diferido e nil 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`.
sentAtString or nil: Quando saiu. É nil até o despacho estar concluído, e é por isso que `status`, e não este, é o campo em que basear a lógica.
tagsHash: As etiquetas indicadas no envio, devolvidas tal como vieram e nunca interpretadas. Sempre um Hash, vazio quando não foram definidas e nunca nil, e só devolvidas: esta lista filtra por `status`, `from`, `broadcast_id` e pela janela de agendamento, por isso uma etiqueta é algo que se lê numa mensagem, não uma forma de a encontrar.
broadcastIdString or nil: A difusão `brd_` de que esta mensagem é uma cópia, ou nil para uma mensagem enviada sozinha.
sourceString: Que superfície pediu o envio: `composer`, `api`, `mcp`, `ai` ou `queue`. `api` é este cliente.
createdAtString: 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.
trackingHash: 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 um `openCount` de 0 se leria como «ninguém a abriu».
translationHash: 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`.

O rastreio de um item

opensBoolean: 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.
clicksBoolean: 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.
openedBoolean: Indica se foi registada alguma abertura contabilizada, derivado de `openCount` ser superior a 0.
clickedBoolean: Indica se foi registado algum clique contabilizado, derivado de `clickCount` ser superior a 0.
openCountInteger: 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ó.
clickCountInteger: 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.
firstOpenAtString or nil: A primeira abertura contabilizada entre todas as cópias, e nil enquanto não houver nenhuma. Os acessos automáticos nunca a alteram.