SDK
Monitorização de aberturas e cliques
`emails.getTracking` e todo o recurso `tracking`.
Uma mensagem
const report = await openemail.emails.getTracking('msg_…') console.log(report.openCount, 'opens from', report.recipients.length, 'recipients')for (const link of report.links) console.log(link.url, link.clickCount)Uma mensagem que nunca foi monitorizada lança um OpenEmailApiError cujo isNotFound é 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.
Em toda a caixa de correio
await openemail.tracking.list({ opened: false, days: 7, limit: 100 })await openemail.tracking.getStats({ days: 30, offsetMinutes: -new Date().getTimezoneOffset() })await openemail.tracking.get('msg_…')await openemail.tracking.listOpens('msg_…', { includeMachine: true })await openemail.tracking.listClicks('msg_…')list, listOpens e listClicks resolvem para arrays simples. get, listOpens e listClicks aceitam o id de envio msg_… ou o tmsg_… do próprio registo de monitorização.
Um recurso próprio em vez de campos em emails, e a razão é a cobertura: emails lista registos de envio, que só existem para correio que esta API tratou. O compositor, 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` / `clicks` | O que foi APLICADO: se a mensagem saiu com um pixel ou com ligações reescritas. |
| `opened` / `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.getStats são sobre mensagens MONITORIZADAS, nunca sobre tudo o que foi enviado. Caso contrário, uma caixa de correio que monitoriza uma mensagem em cada dez pareceria ter colapsado.
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.
daysnumber- Quantos dias para trás a partir de agora se deve olhar, de 1 a 365 e 30 por omissão; fora desse intervalo é um 422. A janela é medida sobre quando o registo de monitorização foi criado, e só são listados registos cujo envio tenha efetivamente saído.
limitnumber- No máximo este número de mensagens, de 1 a 200 e 50 por omissão, das mais recentes para as mais antigas. Não há cursor: isto é um relatório sobre uma janela e não um feed, por isso é limitado por `days` e `limit` e lido por inteiro.
Resposta: TrackingResource
object'tracking'- Sempre `'tracking'` num relatório obtido por si próprio, através de `tracking.get`, `tracking.list` ou `emails.getTracking`. O mesmo relatório aninhado como `email.tracking` numa mensagem obtida chega sem esta chave, porque aí faz parte desse objeto em vez de ser algo que foi obtido.
idstring- O id do próprio registo de monitorização, `tmsg_…`. É a chave das chamadas por acesso `listOpens` e `listClicks`; um `msg_…` entregue a elas é primeiro resolvido para este.
sendIdstring | null- O envio `msg_…` a que isto corresponde, e null quando não foi escrito nenhum registo de envio. O compositor, o `sendEmail` do MCP e o assistente enviam todos sem um. A monitorização cobre a caixa de correio, não apenas o tráfego de API.
threadIdstring | null- Preenchido após a transmissão para que uma interface de leitura consiga voltar a encontrar a mensagem, e null quando o driver não reportou nenhum. Não é determinante: um registo com isto a null continua a contar.
messageIdstring | null- O Message-ID RFC 5322, não o nosso id. Também preenchido após a transmissão, e null quando o transporte não devolveu nada com que o preencher.
subjectstring | null- O assunto tal como estava na altura do envio. Null numa mensagem registada sem um.
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.
sourceEmailSource | (string & {})- Que superfície o enviou: `composer`, `api`, `mcp`, `ai` ou `queue`. Tipado como união aberta, para que uma superfície que este SDK ainda não nomeia não seja uma alteração disruptiva.
sentAtstring | null- Quando a mensagem partiu, como um instante ISO-8601. Null 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».
openCountnumber- 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.
clickCountnumber- 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.
openCountRawnumber- Todas as obtenções do pixel, scanners e proxies de privacidade incluídos. `openCountRaw - openCount` é quantos o classificador pôs de parte, e a única prova disponível de que a filtragem sequer aconteceu.
clickCountRawnumber- Todas as visitas a uma ligação reescrita, acessos de máquinas e repetições incluídos.
firstOpenAtstring | null- A abertura contabilizada mais antiga nas cópias, e null enquanto não houver nenhuma. Os acessos de máquinas nunca a movem.
lastOpenAtstring | null- A abertura contabilizada mais recente nas cópias, null enquanto não houver nenhuma.
firstClickAtstring | null- O clique contabilizado mais antigo nas cópias, null enquanto não houver nenhum.
lastClickAtstring | null- O clique contabilizado mais recente nas cópias, null enquanto não houver nenhum.
recipientsTrackingRecipientResource[]- 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.
recipients[].emailstring | null- Para quem foi esta cópia, em minúsculas e tal como estava na altura do envio. Null exatamente quando `attributed` é false.
recipients[].kind'to' | 'cc' | 'bcc' | null- Em que cabeçalho o endereço apareceu, para que um relatório se leia como a mensagem se lia. Null na cópia partilhada, que não pertence a nenhum endereço.
recipients[].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.
recipients[].openCountnumber- 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ó.
recipients[].clickCountnumber- Cliques contabilizados só nesta cópia, desduplicados por ligação e não por cópia.
recipients[].firstOpenAtstring | null- A abertura contabilizada mais antiga nesta cópia, null enquanto não houver nenhuma.
recipients[].lastOpenAtstring | null- A abertura contabilizada mais recente nesta cópia, null enquanto não houver nenhuma.
recipients[].firstClickAtstring | null- O clique contabilizado mais antigo nesta cópia, null enquanto não houver nenhum.
recipients[].lastClickAtstring | null- O clique contabilizado mais recente nesta cópia, null enquanto não houver nenhum.
linksTrackingLinkResource[]- 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.
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 `listClicks` possa ser ligado de volta à entrada aqui.
links[].urlstring- Para onde a ligação vai realmente, tal como estava na mensagem antes da reescrita. O redirecionador resolve um id de volta para isto e encaminha o visitante.
links[].labelstring | null- O texto da âncora tal como apareceu na mensagem, ou null 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 monitorização, e nunca substitui `url`.
links[].clickCountnumber- Visitas contabilizadas a esta ligação, somadas sobre as cópias. A mesma janela de trinta segundos por ligação que `clickCount` na mensagem.
links[].clickCountRawnumber- Todas as visitas a esta ligação, acessos de máquinas e repetições incluídos.