Referência da API

Uso e métricas

O consumo do plano e as métricas de entrega, abertura e clique.

Consulte quanto do plano o time já usou e as métricas de entrega dos seus e-mails.

#Uso do plano

GET/usage

Chave de acesso total

Cotas de envio do dia e do mês (dias e meses em UTC), domínios, inboxes, pessoas no time, campanhas do mês (broadcasts: enviadas, enviando ou agendadas), execuções de automação iniciadas no mês, créditos de IA, se o envio está pausado e o limite de requisições por segundo. limit: null significa sem limite.

GET /usage

cURL

curl https://api.postal.so/usage \
  -H "Authorization: Bearer $POSTAL_API_KEY"

Node.js

const response = await fetch('https://api.postal.so/usage', {
  headers: {
    Authorization: `Bearer ${process.env.POSTAL_API_KEY}`,
  },
});

const data = await response.json();

Python

import os
import requests

response = requests.get(
    "https://api.postal.so/usage",
    headers={"Authorization": f"Bearer {os.environ['POSTAL_API_KEY']}"},
    timeout=10,
)

data = response.json()

PHP

$client = new \GuzzleHttp\Client(['base_uri' => 'https://api.postal.so']);

$response = $client->get('usage', [
    'headers' => ['Authorization' => 'Bearer '.getenv('POSTAL_API_KEY')],
]);

$data = json_decode($response->getBody(), true);

200Resposta

{
  "object": "usage",
  "plan": {
    "id": "pro",
    "name": "Pro",
    "marketing_id": "free",
    "marketing_name": "Free"
  },
  "emails": {
    "daily": {
      "used": 1840,
      "limit": null,
      "sent": 1840,
      "received": 0,
      "resets_at": "2026-10-25T00:00:00Z"
    },
    "monthly": {
      "used": 31207,
      "limit": 50000,
      "sent": 31207,
      "received": 0,
      "resets_at": "2026-11-01T00:00:00Z"
    }
  },
  "domains": {
    "used": 2,
    "limit": 10
  },
  "team_members": {
    "used": 4,
    "limit": 10
  },
  "inboxes": {
    "used": 1,
    "limit": 10
  },
  "features": {
    "custom_inbound_domains": true,
    "postal_branding": false,
    "ai_assistant": true
  },
  "broadcasts": {
    "used": 3,
    "limit": null
  },
  "automation_runs": {
    "used": 318,
    "limit": 10000
  },
  "ai_credits": {
    "used": 12,
    "limit": 100,
    "remaining": 88,
    "resets_at": "2026-11-01T00:00:00Z"
  },
  "sending": {
    "paused": false,
    "paused_at": null,
    "reason": null
  },
  "rate_limit": {
    "limit": 10,
    "duration": "1s"
  }
}

#Métricas de e-mail

GET/emails/metrics

Chave de acesso total

Contagens e taxas calculadas a partir dos eventos no período. Sem dimensions, só vêm os totais; com period, vem uma linha por período (inclusive os vazios). Com domain ou broadcast (campanha), cada linha traz também o nome (domain_name, broadcast_name). Os resultados ficam em cache por até 15 minutos.

Contagens: sent, delivered, delivery_delayed, bounced, bounced_permanent, bounced_transient, bounced_undetermined, complained, failed, suppressed, opened, unique_opened, clicked, unique_clicked, received, unsubscribed. Taxas (de 0 a 1): delivery_rate (entregues / enviados), open_rate e click_rate (únicos / entregues), bounce_rate (bounces / enviados), complaint_rate e unsubscribe_rate (sobre entregues).

Parâmetros de consulta

start_datestring
Início, em ISO 8601. Padrão: 6 dias antes do fim, à meia-noite.
end_datestring
Fim, em ISO 8601. Padrão (e máximo): agora.
timezonestring
Fuso IANA para datas sem fuso e para os períodos, como America/Sao_Paulo. Padrão: UTC.
granularitystring
hourly, daily (padrão), weekly ou monthly. No máximo 10.000 períodos.
metricsstring
Métricas separadas por vírgula (ou o parâmetro repetido). Padrão: todas.
dimensionsstring
Agrupamentos: period, domain, email e/ou broadcast.
domain_idstring
Até 100 IDs de domínio, separados por vírgula.
email_idstring
Até 100 IDs de e-mail, separados por vírgula.
broadcast_idstring
Até 100 IDs de campanha, separados por vírgula.

Erros

422validation_error
Data, fuso, granularidade, métrica ou dimensão inválida, ou período longo demais para a granularidade.

GET /emails/metrics

cURL

curl 'https://api.postal.so/emails/metrics?start_date=2026-10-20&end_date=2026-10-22T23:59:59&timezone=America/Sao_Paulo&metrics=sent,delivered,delivery_rate&dimensions=period' \
  -H "Authorization: Bearer $POSTAL_API_KEY"

Node.js

const response = await fetch('https://api.postal.so/emails/metrics?start_date=2026-10-20&end_date=2026-10-22T23:59:59&timezone=America/Sao_Paulo&metrics=sent,delivered,delivery_rate&dimensions=period', {
  headers: {
    Authorization: `Bearer ${process.env.POSTAL_API_KEY}`,
  },
});

const data = await response.json();

Python

import os
import requests

response = requests.get(
    "https://api.postal.so/emails/metrics",
    headers={"Authorization": f"Bearer {os.environ['POSTAL_API_KEY']}"},
    params={
        "start_date": "2026-10-20",
        "end_date": "2026-10-22T23:59:59",
        "timezone": "America/Sao_Paulo",
        "metrics": "sent,delivered,delivery_rate",
        "dimensions": "period",
    },
    timeout=10,
)

data = response.json()

PHP

$client = new \GuzzleHttp\Client(['base_uri' => 'https://api.postal.so']);

$response = $client->get('emails/metrics', [
    'headers' => ['Authorization' => 'Bearer '.getenv('POSTAL_API_KEY')],
    'query' => [
        'start_date' => '2026-10-20',
        'end_date' => '2026-10-22T23:59:59',
        'timezone' => 'America/Sao_Paulo',
        'metrics' => 'sent,delivered,delivery_rate',
        'dimensions' => 'period',
    ],
]);

$data = json_decode($response->getBody(), true);

200Resposta

{
  "object": "metrics",
  "start_date": "2026-10-20T03:00:00.000Z",
  "end_date": "2026-10-23T02:59:59.000Z",
  "metrics": ["sent", "delivered", "delivery_rate"],
  "dimensions": ["period"],
  "granularity": "daily",
  "totals": {
    "sent": 3120,
    "delivered": 3087,
    "delivery_rate": 0.9894
  },
  "data": [
    {
      "period": "2026-10-20T00:00:00-03:00",
      "sent": 1004,
      "delivered": 995,
      "delivery_rate": 0.991
    },
    {
      "period": "2026-10-21T00:00:00-03:00",
      "sent": 1130,
      "delivered": 1116,
      "delivery_rate": 0.9876
    },
    {
      "period": "2026-10-22T00:00:00-03:00",
      "sent": 986,
      "delivered": 976,
      "delivery_rate": 0.9899
    }
  ]
}