Limites

#Requisições por segundo

Cada time tem um limite de requisições por segundo, somando todas as chaves. O valor depende do plano:

Valores atualizados da GET /plans ao abrir a página.

O limite em vigor para o seu time aparece em GET /usage (rate_limit). Os apps que têm só uma chave de envio também enxergam o limite: GET /usage aceita chaves sending_access, e os cabeçalhos X-RateLimit-* vêm em toda resposta, inclusive no envio. Toda resposta traz os cabeçalhos:

Passou do limite, a resposta é 429 rate_limit_exceeded. Para enviar muitos e-mails, use o envio em lote: 100 e-mails contam como uma requisição.

O limite é do time, não da chave, e vale também para o servidor MCP. Os SDKs leem os cabeçalhos para você: postal.rateLimit (Node.js) e $postal->rateLimit() (PHP) guardam o limite da última resposta, mesmo com uma chave só de envio, e esperam o Retry-After antes de repetir um 429.

#Cotas de envio

Os envios contam quando o e-mail é criado (inclusive agendados e testes de template). Cada destinatário de uma campanha, cada teste de campanha e cada e-mail de automação também conta. O dia e o mês são contados em UTC.

Valores atualizados da GET /plans ao abrir a página.

Ao atingir a cota, os envios recebem 429 daily_quota_exceeded ou 429 monthly_quota_exceeded (no SMTP, 452 4.5.3). Uma campanha que esbarra na cota no meio do envio fica pausada e continua sozinha quando ela renova; um envio de automação falha, e a execução também. Nos planos que permitem, você pode ativar o envio além da cota no painel, em Cobrança: os e-mails extras são cobrados por mil, sem bloqueio. O plano continua o mesmo; você paga só pelos pacotes a mais, na próxima fatura. Acompanhe o consumo em GET /usage.

Reputação da conta. O limite diário que vale é o menor entre o do plano e o teto da reputação da conta: uma pontuação de 0 a 100 que começa em 0 nas contas novas e sobe a cada dia de envios sem bounces nem reclamações. Nos níveis 1 a 4, o teto é de 500, 2.000, 5.000 e 10.000 e-mails por dia; no nível 5, vale só o limite do plano. O limite em vigor está em emails.daily.limit de GET /usage, com plan_limit (o do plano) e limited_by (plan ou reputation), e o bloco reputation traz a pontuação, o nível e o próximo nível. Quando é a reputação que limita, a mensagem do 429 daily_quota_exceeded diz o nível e o teto.

Adicional de envios. Quando o plano do time tem um limite mensal e oferece o Adicional de envios, o dono ou um admin compra, num pagamento único, uma reserva de envios que só é usada depois que a cota mensal acaba: primeiro a cota do plano, depois a reserva (um crédito por e-mail, os que vencem antes primeiro), depois o envio além da cota, se o time o ligou, e só então a recusa. As campanhas não usam a reserva, os e-mails para endereços de teste não gastam crédito, e o limite diário do plano continua valendo. A mensagem do 429 monthly_quota_exceeded diz onde comprar quando dá. Veja Adicional de envios e a referência da API.

#Recursos por plano

Planos e preços: postal.so/precos ou, por API, GET /plans (público, sem chave).

Valores atualizados da GET /plans ao abrir a página.

Times podem ter limites ajustados individualmente. O valor que vale para você é sempre o de GET /usage.

#Limites e recursos do plano

Cada plano define, por time, quantas coisas você pode ter e quais recursos estão incluídos. Passar do limite de um item ou usar um recurso que o plano não inclui responde 403 plan_limit_reached, com uma mensagem que diz qual. A lista completa, com o texto de cada recurso e se a API já o aplica (enforced), vem em GET /plans (feature_catalog), e os valores do seu time em GET /usage. Nos números, null é ilimitado e 0 é não incluído; nos recursos liga/desliga, 1 é incluído e 0 não.

Quantidade

Só bloqueiam a criação de mais um item. O que já existe nunca é apagado.

Contatos acima do limite. O limite de contatos do plano de marketing também pode ser ultrapassado, como o de e-mails: em Cobrança, o dono ou admin do time liga Continuar adicionando contatos acima do limite do plano (um botão para cada produto, desligado por padrão). Ligado, importações, formulários, a API e as integrações de CRM deixam de recusar com 403 plan_limit_reached ao chegar no limite, e os contatos extras são cobrados por pacote de 1.000 (arredondando para cima) na próxima fatura, sem trocar de plano. O que se cobra é o maior número de contatos que o time teve no período de cobrança (ou de contatos que receberam campanhas no ciclo, se for maior: veja abaixo), e apagar contatos depois não baixa o que já foi medido. Descadastrados e endereços suprimidos contam como contato, como sempre. Só vale com assinatura de marketing ativa, num plano que permita excedente e que tenha preço de contatos extras; sem isso, o limite continua recusando. A mensagem de recusa diz como ligar quando a opção está disponível.

Adicional de contatos. Quando o plano de marketing do time oferece o Adicional de contatos, o dono ou um admin soma contatos ao limite sem trocar de plano: o preço do pacote entra na fatura da assinatura e o limite passa a ser o do plano mais o dos pacotes. O limite que a API confere (403 plan_limit_reached) e o que GET /usage mostra já incluem os pacotes. Só valem com um plano de marketing pago e ativo. Veja Adicional de contatos e a referência da API.

Contatos que recebem campanhas no ciclo

O limite de contatos do plano de marketing (com o Adicional de contatos) vale também para quem recebe campanhas: no ciclo de uso do time (o mês que renova no dia do seu plano), as campanhas e os e-mails de automação podem ir para até esse número de contatos diferentes. Cada endereço conta uma vez por ciclo. Quem já recebeu campanha no ciclo continua contando até a renovação, mesmo se for apagado, e apagar e criar de novo o mesmo endereço não conta duas vezes. Apagar contatos que ainda não receberam campanha libera espaço na hora. Enviar várias campanhas para os mesmos contatos não consome mais. Os e-mails transacionais não contam.

Exemplo, com limite de 50.000 contatos: enviar 5 campanhas para os mesmos 50.000 contatos no ciclo está dentro do plano. Apagar os 50.000 que já receberam e importar outros 50.000 no mesmo ciclo passa do limite: a campanha para os novos é recusada até a renovação.

Uma campanha que passaria do limite é recusada inteira, sem enviar nada, com 422 cycle_recipients_limit, uma mensagem com os números, a data da renovação e o que fazer, e o bloco cycle_recipients (new, used, limit, remaining e resets_at). A Postal confere de novo quando uma campanha agendada vai sair: se não couber mais, ela fica pausada com o mesmo motivo. Um e-mail de automação para um contato que ainda não recebeu nada no ciclo, com o limite cheio, é pulado. O dono e os admins recebem um e-mail ao chegar a 80% e a 100%. Com o excedente de contatos ligado, nada é recusado e os contatos acima do limite são cobrados como contatos extras. Sem limite de contatos, não há limite de destinatários. O contador está em GET /usage (marketing_recipients) e em Configurações › Uso, e o efeito de uma campanha, antes de enviar, em GET /broadcasts/audience.

Outros limites mensais não dão 403: emails_per_day e emails_per_month dão 429 (veja cotas de envio); ai_credits, 429 ai_credits_exhausted; email_verifications_per_month, 403 se o plano não inclui a validação de e-mails e 429 verification_credits_exhausted quando os créditos acabam; e automation_runs: acima do limite, as novas execuções de automação não começam (ficam como skipped).

Recursos liga/desliga

retention_days, priority_support, uptime_sla e dedicated_manager são informativos: a API não bloqueia nada por eles (a retenção é de 30 dias para todos, e o suporte é combinado à parte).

Quando o plano cai

Quando o plano muda, a quantidade que o time já tem pode passar do novo limite. Nada é apagado: de domínios, inboxes, templates, layouts, chaves de API, webhooks, automações, segmentos, tópicos e formulários, os mais antigos até o limite continuam ativos e os mais novos ficam com paused_by_plan: true. Um item pausado aparece nas listas e pode ser lido e excluído, mas não alterado nem usado: o domínio não envia, a chave de API não autentica, o webhook não recebe eventos, o template não envia, o formulário sai do ar, a automação não dispara, o segmento não serve de público e a inbox não roda o agente (ela continua recebendo e-mails). Qualquer tentativa de alterar responde 403 paused_by_plan. Os itens voltam sozinhos quando o plano, a faixa de volume ou a contagem permitem, e GET /usage lista o que está pausado em paused. Contatos, pessoas no time e conexões não são pausados: o limite só impede adicionar mais.

As cotas de e-mails por mês e o número de contatos seguem a faixa de volume contratada (veja Planos), e um time pode ter limites ajustados individualmente. O valor que vale para você é sempre o de GET /usage.

A escala de volume é feita de faixas definidas pela Postal (por exemplo 3.000, 50.000, 100.000 e 250.000 e-mails por mês): cada plano atende algumas dessas faixas, com o preço de cada uma, e acima da última faixa só o plano sob medida atende. A lista das faixas e das que cada plano atende está em GET /plans (volume_bands e bands).

#Tamanhos e quantidades