Guia do desenvolvedorReferência
Limites e níveis de confiança
Níveis de confiança do Couryo, limites por dia e por mês, limites de cada plano (e-mails e domínios), limite de gasto, cabeçalhos de limite de requisição, pausas e como pedir revisão.
O Couryo protege a reputação de todos os clientes sem pegar ninguém de surpresa. Os limites são públicos, aparecem no painel e nas mensagens de erro da API, e toda pausa vem com motivo e números.
Níveis de confiança#
| Nível | Como entra | Limite |
|---|---|---|
| 0, sandbox | conta criada | 25 por dia, só para os e-mails da própria conta |
| 1, novo | um domínio verificado (DKIM, return path e DMARC) | 100 por dia e 3 mil por mês |
| 2, verificado | 7 dias limpos e CNPJ conferido ou forma de pagamento cadastrada | 1 mil por dia, dobrando a cada semana limpa até 10 mil |
| 3, confiável | 30 dias limpos no nível 2 e plano pago | o volume do seu plano, com o limite de gasto |
- Você sobe sozinho. Não há aprovação manual nem formulário.
- O painel mostra o que falta, por exemplo: "Faltam 4 dias limpos para o nível 2".
- "Dias limpos" são dias sem pausa por devolução ou reclamação.
- Os limites contam destinatários (
to+cc+bcc), não chamadas. O dia vira à meia-noite no fuso da conta; o mês é o período pago ou, no Grátis, o mês do calendário. - Chaves
ck_test_não contam em nenhum limite de envio.
O limite de cada momento é o menor entre o do nível e o do plano: no plano Grátis, o teto é de 100 por dia mesmo no nível 2.
Limites do plano#
| Plano | E-mails por mês | Por dia | Domínios | Logs |
|---|---|---|---|---|
| Grátis | 3.000 | até 100 | 1 | 7 dias |
| Pro | 50 mil incluídos, excedente por mil | o do nível | até 10 | 30 dias |
| Escala | 200 mil incluídos, excedente por mil | o do nível | até 50 | 90 dias |
| Empresa | sob medida | sob medida | sem limite | estendido |
- Domínios contam todos os projetos da conta. Acima do limite, a API responde
403 domain_limit_reached; apagar um domínio libera a vaga. - No Grátis, o envio para na cota do mês (
monthly_limit_reached) e volta no mês seguinte, sem cobrança. - Nos planos pagos, o excedente é cobrado por bloco de mil e-mails iniciado. Veja os preços.
Limite de gasto#
Em Cobrança, você define quanto aceita pagar de excedente por mês. Quando o excedente chega a esse valor, todo o envio para (transacional e marketing) com spend_limit_reached, até você aumentar o limite ou o período virar. Nada é cobrado acima do teto.
Limites que pausam#
| Medida | Pausa quando |
|---|---|
| Taxa de devolução | passa de 3% nas últimas 24 horas, com pelo menos 50 enviados |
| Taxa de reclamação (marcado como spam) | passa de 0,05% nos últimos 7 dias, com pelo menos 200 enviados e 2 reclamações |
As taxas são da conta, medidas em tempo real, e ficam bem abaixo do que os grandes provedores toleram, para corrigir cedo. Bloqueios por política do destino (5.7.x) não contam na taxa de devolução.
Pausas#
Quando uma taxa passa do limite, a pausa é gradual:
- o envio de marketing para;
- o transacional crítico (senha, login, cobrança) continua, com até 30 por dia;
- você recebe um e-mail com o motivo, os números e o que corrigir.
Acima de 10% de devolução ou de 0,5% de reclamação, a pausa é total, inclusive no motor de envio, e só uma pessoa da equipe libera. Corte total também em fraude evidente, como phishing ou lista comprada.
Durante a pausa, a API responde sending_paused com o motivo, os números e como corrigir, e o painel mostra o mesmo, com o botão Pedir revisão.
Pedir revisão#
Discorda de uma pausa ou já corrigiu? Use o botão Pedir revisão no painel e explique o caso.
- Na hora: um agente de IA analisa o pedido com os dados da conta e decide os casos claros. Aprovado, a conta fica 48 horas em observação (status
limited), com até 50 por dia, e volta ao normal se as taxas continuarem boas. - Em até 1 dia útil: se a dúvida continuar, uma pessoa da equipe revisa e responde com o motivo.
As regras completas estão na política de uso aceitável e de suspensão.
Limite de requisições#
Cada chave tem uma janela de 1 segundo (o padrão é 10 chamadas por segundo). Toda resposta traz os cabeçalhos:
| Cabeçalho | O que diz |
|---|---|
RateLimit-Limit |
quantas chamadas cabem na janela |
RateLimit-Remaining |
quantas ainda restam |
RateLimit-Reset |
em quantos segundos a janela recomeça |
Retry-After |
em 429 rate_limited, quantos segundos esperar |
Ao receber 429, espere o Retry-After e tente de novo com a mesma Idempotency-Key. Para mandar muitos e-mails de uma vez, use o lote: até 100 por chamada.
Tamanhos#
| O quê | Limite |
|---|---|
Destinatários por e-mail (to + cc + bcc) |
50 |
| E-mails por lote | 100 |
| Anexos por e-mail | 20 |
| Corpo da chamada (com anexos em Base64) | 30 MB |
html ou text |
5 MB cada |
Agendamento (scheduled_at) |
até 30 dias à frente |