Ruby

Rastreio de aberturas e cliques

`emails.get_tracking` e todo o espaço de nomes `tracking`.

Uma mensagem

tracking.rb

report = client.emails.get_tracking("msg_3f9a1c07d2b84e6a9c5b1f20") puts "#{report[:openCount]} opens from #{report[:recipients].size} recipients"report[:links].each { |link| puts "#{link[:url]} #{link[:clickCount]}" }

Uma mensagem que nunca foi rastreada lança um OpenEmail::NotFoundError, cujo not_found? é true, e não um relatório vazio. «Não registámos nada» e «ninguém abriu» são respostas diferentes e não podem partilhar uma resposta. Uma mensagem enviada com uma chave de teste nunca é rastreada, por isso lança sempre um.

Em toda a caixa de correio

tracking_report.rb

client.tracking.list(opened: false, days: 7, limit: 100)client.tracking.get_stats(days: 30, offset_minutes: Time.now.utc_offset / 60)client.tracking.get("msg_3f9a1c07d2b84e6a9c5b1f20")client.tracking.list_opens("msg_3f9a1c07d2b84e6a9c5b1f20", include_machine: true)client.tracking.list_clicks("msg_3f9a1c07d2b84e6a9c5b1f20")

list, list_opens e list_clicks devolvem uma OpenEmail::Page, e list_all, iterate, list_all_opens, iterate_opens, list_all_clicks e iterate_clicks percorrem todas as páginas por si. get, list_opens e list_clicks aceitam o id de envio msg_… ou o tmsg_… do próprio registo de rastreio.

Um espaço de nomes próprio em vez de métodos em emails, e a razão é a cobertura: emails lista registos de envio, que só existem para correio que esta API tratou. O editor, as ferramentas MCP e o assistente enviam todos sem um, por isso um relatório construído sobre emails seria um relatório sobre o seu tráfego de API em vez de sobre a caixa de correio.

Ler os números com honestidade

Par	O que significa
opens e clicks	O que foi APLICADO: se a mensagem saiu com um pixel ou com ligações reescritas.
opened e clicked	O que aconteceu.
openCount	Acessos contabilizados. Scanners e proxies de privacidade excluídos.
openCountRaw	Todos os acessos. Citar isto como envolvimento é como uma taxa de abertura ultrapassa os 100%.
attributable	Se uma leitura pode sequer ser atribuída a um destinatário identificado.

As taxas de tracking.get_stats são sobre mensagens RASTREADAS, nunca sobre tudo o que foi enviado. Caso contrário, uma caixa de correio que rastreia uma mensagem em cada dez pareceria ter colapsado. openRate e clickRate são percentagens arredondadas a uma casa decimal, como 42.5, e não frações entre 0 e 1.

Parâmetros: tracking.list

openedBoolean: `true` seleciona mensagens com pelo menos uma abertura contabilizada, `false` seleciona mensagens monitorizadas sem nenhuma. Nenhum é o valor por omissão, e `false` nunca significa correio não monitorizado, que não aparece de todo nesta lista.
clickedBoolean: O mesmo filtro para cliques contabilizados, aplicado independentemente de `opened`. Ambos podem ser dados, e as mensagens têm de satisfazer os dois.
daysInteger: Quantos dias para trás a partir de agora se deve olhar, de 1 a 365 e 30 por omissão, e fora desse intervalo é um 422. A janela é medida sobre quando o registo de rastreio foi criado, e só são listados registos cujo envio tenha efetivamente saído.
minutesInteger: A janela em minutos, de 1 a 527040, que prevalece sobre `days` quando ambos estão definidos. Uma janela inferior a um dia precisa de um `grain` mais fino.
grainString: `minute`, `hour` ou `day`, com `day` por omissão. Apenas arredonda para baixo o início da janela, para que esta lista corresponda a `get_stats` lido com a mesma granularidade, e não dá forma a nada na resposta.
limitInteger: Relatórios por página, de 1 a 200 e 50 por omissão, dos mais recentes para os mais antigos. Devolva o `next_cursor` da página como `cursor:`, com os mesmos filtros, para obter a seguinte, ou deixe `list_all` e `iterate` percorrer toda a janela.
cursorString: O `next_cursor` da página anterior, um id `tmsg_`.
api_keyString: Lista com esta chave em vez da do cliente.

Resposta: o relatório de rastreio

emails.get_tracking e tracking.get devolvem um relatório como Hash com chaves Symbol, e tracking.list devolve uma página deles.

objectString: Sempre `tracking` num relatório obtido por si próprio, através de `tracking.get`, `tracking.list` ou `emails.get_tracking`. O mesmo relatório aninhado como `tracking` numa mensagem de `emails.get` chega sem esta chave, porque aí faz parte dessa mensagem em vez de ser algo que foi obtido.
idString: O id do próprio registo de rastreio, `tmsg_…`. É a chave de `list_opens` e `list_clicks`, e um `msg_…` entregue a elas é primeiro resolvido para este.
sendIdString or nil: O envio `msg_…` a que isto corresponde, e nil quando não foi escrito nenhum registo de envio. O editor, o `sendEmail` do MCP e o assistente enviam todos sem um. O rastreio cobre a caixa de correio, não apenas o tráfego de API.
threadIdString or nil: Preenchido após a transmissão para que uma interface de leitura consiga voltar a encontrar a mensagem, e nil quando o driver não reportou nenhum. Não é determinante: um registo com isto a nil continua a contar.
messageIdString or nil: O Message-ID RFC 5322, não o nosso id. Também preenchido após a transmissão, e nil quando o transporte não devolveu nada com que o preencher.
subjectString or nil: O assunto tal como estava na altura do envio. nil numa mensagem registada sem assunto.
fromString: O endereço de envio, copiado para o registo em vez de obtido por junção a partir do envio. Os relatórios são lidos muito depois do facto, e um endereço entretanto corrigido ou removido reescreveria a história.
sourceString: Que superfície o enviou: `composer`, `api`, `mcp`, `ai` ou `queue`. Pode aparecer uma superfície que esta gem ainda não nomeia, por isso trate um valor desconhecido como informação e não como um erro.
sentAtString or nil: Quando a mensagem partiu, como um instante ISO 8601. nil num registo cujo envio nunca se concluiu. `tracking.list` exclui esses, `get` não.
opensBoolean: Se um pixel foi APLICADO a esta mensagem. Isto é o que foi feito, não o que a definição da conta diz agora.
clicksBoolean: Se as ligações desta mensagem foram reescritas. False quando o corpo não trazia ligações, porque então nada foi alterado e um registo a afirmar o contrário não poderia ser reconciliado com os bytes.
openedBoolean: Se alguma abertura contabilizada foi registada nas cópias. Leia-o contra `opens`: não haver dados porque nenhum foi recolhido é um facto diferente de ninguém ter lido a mensagem.
clickedBoolean: Se algum clique contabilizado foi registado. Prova mais forte do que uma abertura, já que as imagens são bloqueadas muito mais vezes do que as ligações ficam por seguir.
attributableBoolean: Se todas as leituras aqui podem ser atribuídas a um destinatário identificado. False no momento em que uma cópia não atribuída mostra atividade contabilizada, que é o caso de vários destinatários em que um corpo vai para toda a lista sob um único token, por isso verifique-o antes de escrever «o Bob não abriu isto».
openCountInteger: Aberturas que se crê terem sido causadas por uma pessoa, somadas sobre as cópias. Os acessos de máquinas são excluídos e repetições dentro de trinta segundos colapsam numa só, por isso este é o número a pôr à frente de um leitor.
clickCountInteger: Cliques contabilizados, somados sobre as cópias. Desduplicados por ligação e não por mensagem, por isso duas ligações diferentes seguidas com segundos de intervalo são dois cliques.
openCountRawInteger: Todas as obtenções do pixel, scanners e proxies de privacidade incluídos. `openCountRaw` menos `openCount` é quantas foram postas de parte, entre obtenções automáticas e repetições em menos de trinta segundos, e a única prova disponível de que a filtragem sequer aconteceu.
clickCountRawInteger: Todas as visitas a uma ligação reescrita, acessos de máquinas e repetições incluídos.
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.
lastOpenAtString or nil: A abertura contabilizada mais recente nas cópias, nil enquanto não houver nenhuma.
firstClickAtString or nil: O clique contabilizado mais antigo nas cópias, nil enquanto não houver nenhum.
lastClickAtString or nil: O clique contabilizado mais recente nas cópias, nil enquanto não houver nenhum.
recipientsArray<Hash>: Uma entrada por cópia monitorizada: por destinatário onde o transporte permite que os bytes difiram por pessoa, e uma única entrada partilhada onde não permite. A entrada partilhada é descartada a menos que algo lhe tenha efetivamente chegado, para que uma linha «alguém» intocada nunca fique ao lado de nomes reais.
linksArray<Hash>: Todas as ligações que foram reescritas nesta mensagem, ordenadas pela posição que ocupavam no corpo. Vazio quando não houve nenhuma: uma mensagem enviada com `clicks` desligado, ou uma cujo corpo não trazia qualquer ligação.

Cada entrada em recipients

emailString or nil: Para quem foi esta cópia, em minúsculas e tal como estava na altura do envio. nil exatamente quando `attributed` é false.
kindString or nil: `to`, `cc` ou `bcc`: em que cabeçalho o endereço apareceu, para que um relatório se leia como a mensagem se lia. nil na cópia partilhada, que não pertence a nenhum endereço.
attributedBoolean: Se esta linha identifica uma pessoa. Leia-o antes de `email`: false é a cópia partilhada, listada assim que algum acesso lhe chega, e pôr um nome nesse acesso, mesmo numa mensagem com um único destinatário, inventaria o único facto que o mecanismo não consegue fornecer.
openCountInteger: Aberturas contabilizadas só nesta cópia, sob as mesmas exclusões do total da mensagem: acessos de máquinas descartados e repetições dentro de trinta segundos colapsadas numa só.
clickCountInteger: Cliques contabilizados só nesta cópia, desduplicados por ligação e não por cópia.
firstOpenAtString or nil: A abertura contabilizada mais antiga nesta cópia, nil enquanto não houver nenhuma.
lastOpenAtString or nil: A abertura contabilizada mais recente nesta cópia, nil enquanto não houver nenhuma.
firstClickAtString or nil: O clique contabilizado mais antigo nesta cópia, nil enquanto não houver nenhum.
lastClickAtString or nil: O clique contabilizado mais recente nesta cópia, nil enquanto não houver nenhum.

Cada entrada em links

idString: O id da própria ligação, `lnk_…`. É o valor que o `linkId` de uma linha de clique indica, para que um acesso vindo de `list_clicks` possa ser ligado de volta à entrada aqui.
urlString: Para onde a ligação vai realmente, tal como estava na mensagem antes da reescrita. O redirecionador resolve um id para isto e encaminha o visitante.
labelString or nil: O texto da âncora tal como apareceu na mensagem, ou nil quando a ligação não tinha nenhum, como uma imagem ou um URL solto. Existe para que um relatório possa dizer «a ligação dos preços» em vez de citar um URL com três parâmetros de rastreio, e nunca substitui `url`.
clickCountInteger: Visitas contabilizadas a esta ligação, somadas sobre as cópias. A mesma janela de trinta segundos por ligação que `clickCount` na mensagem.
clickCountRawInteger: Todas as visitas a esta ligação, acessos de máquinas e repetições incluídos.