Migrar para a API Postmaster Tools v2

Este guia descreve as diferenças entre a v1 e a v2 da API Postmaster Tools e como migrar seu aplicativo v1 para a v2.

Visão geral

A versão 2 da API Postmaster Tools apresenta vários recursos novos e consolida a funcionalidade atual para recuperar estatísticas de e-mail. Com a v2, agora você pode:

  • Recuperar estatísticas em períodos em vez de por dia.
  • Consulte o status de conformidade do Sender Policy Framework (SPF), do DomainKeys Identified Mail (DKIM) e da autenticação, relatórios e conformidade de mensagens com base no domínio (DMARC).
  • Recupere estatísticas de vários domínios com uma única chamada de API.

As principais mudanças incluem:

  • O recurso trafficStats foi substituído por domainStats.
  • Os métodos domains.trafficStats.get e domains.trafficStats.list foram substituídos por um único método domains.domainStats.query.
  • Um novo método domains.getComplianceStatus está disponível para recuperar o status de conformidade do SPF, DKIM e DMARC de um determinado domínio.
  • Um novo método domainStats.batchQuery está disponível para recuperar estatísticas de vários domínios em uma única chamada.
  • O termo "métricas" usado na v1 foi renomeado para "estatísticas".

Atualizar para a v2

Para migrar da v1 para a v2, atualize a biblioteca de cliente para a versão mais recente e modifique o código para usar os recursos e métodos da v2.

  1. Atualize sua biblioteca de cliente da API Postmaster Tools para a versão 2 ou mais recente.
  2. Mude todas as chamadas do recurso trafficStats para o recurso domainStats.
  3. Substitua todas as chamadas para domains.trafficStats.get ou domains.trafficStats.list por domains.domainStats.query, fornecendo parâmetros startDate e endDate para especificar o período da consulta.

Recuperar estatísticas de e-mail

Na v1, as métricas de e-mail eram recuperadas usando domains.trafficStats.get para um único dia ou domains.trafficStats.list para vários dias. Na v2, as estatísticas de e-mail são recuperadas usando domains.domainStats.query.

O método domains.domainStats.query permite recuperar estatísticas em um período especificando startDate e endDate.

v1: domains.trafficStats.get

Java

String query = String.format("domains/%s/trafficStats/%s", domainName, date);
TrafficStats trafficStats = service.domains().trafficStats().get(query).execute();

Python

query = 'domains/%s/trafficStats/%s' %(domain_name,date)
traffic_stats = service.domains().trafficStats().get(name=query).execute();

v2: domains.domainStats.query por um único dia

Para recuperar estatísticas de um único dia na v2, chame domains.domainStats.query com os mesmos startDate e endDate.

Java

Date date = new Date().setYear(2024).setMonth(1).setDay(1);
QueryDomainStatsResponse statsResponse = service.domains().domainStats()
        .query("domains/" + domainName)
        .setStartDate(date)
        .setEndDate(date)
        .execute();

Python

date = {'year': 2024, 'month': 1, 'day': 1}
stats = service.domains().domainStats().query(
    parent='domains/' + domain_name,
    startDate=date,
    endDate=date).execute()

v1: domains.trafficStats.list

Java

ListTrafficStatsResponse listTrafficStatsResponse = service.domains().trafficStats().list("domains/" + domainName)
        .execute();

Python

query = 'domains/' + domain_name
list_traffic_stats_response = service.domains().trafficStats().list(parent=query).execute();

v2: domains.domainStats.query para um período

Para extrair estatísticas de um período na v2, chame domains.domainStats.query com um startDate e um endDate.

Java

Date startDate = new Date().setYear(2024).setMonth(1).setDay(1);
Date endDate = new Date().setYear(2024).setMonth(1).setDay(7);
QueryDomainStatsResponse statsResponse = service.domains().domainStats()
        .query("domains/" + domainName)
        .setStartDate(startDate)
        .setEndDate(endDate)
        .execute();

Python

stats = service.domains().domainStats().query(
    parent='domains/' + domain_name,
    startDate={'year': 2024, 'month': 1, 'day': 1},
    endDate={'year': 2024, 'month': 1, 'day': 7}).execute()

Novos recursos da v2

Além de consolidar as estatísticas de tráfego de get e list em query, a v2 apresenta os seguintes recursos.

Recuperar o status de compliance

É possível recuperar o status de conformidade do Sender Policy Framework (SPF), do DomainKeys Identified Mail (DKIM) e do Domain-based Message Authentication, Reporting, and Conformance (DMARC) de um domínio usando domains.getComplianceStatus.

Consulte Recuperar estatísticas de e-mail para conferir um exemplo de código.

Estatísticas de domínio de consultas em lote

É possível recuperar estatísticas de vários domínios com uma única chamada usando domainStats.batchQuery.