Documentação da API

Aprenda a integrar o EmailServer em sua aplicação e começar a enviar e-mails transacionais em minutos.

Início Rápido

Pré-requisitos

Seu Primeiro E-mail

Depois de configurar seu provedor e chave de API, você pode enviar seu primeiro e-mail:

curl -X POST https://emailserver.miltonjunior.dev.br/api/v1/email/send \
  -H "x-api-key: pk_sua_chave_publica.sk_sua_chave_secreta" \
  -H "Content-Type: application/json" \
  -d '{
    "providerId": "ID_DO_SEU_PROVEDOR",
    "to": ["destinatario@exemplo.com"],
    "subject": "Meu primeiro e-mail!",
    "html": "<h1>Olá!</h1><p>Este é meu primeiro e-mail via EmailServer.</p>",
    "text": "Olá! Este é meu primeiro e-mail via EmailServer."
  }'

Autenticação

Todas as requisições à API devem incluir sua chave de API no cabeçalho x-api-key.

Importante: Nunca compartilhe sua chave de API ou a exponha em código público (frontend, repositórios, etc). Use sempre variáveis de ambiente no servidor.

Formato da Chave

A chave de API é composta por duas partes: chave pública (prefixo pk_) e chave secreta (prefixo sk_), separadas por ponto:

pk_abc123def456ghi789.sk_xyz987wvu654tsr321

Exemplo de Requisição

curl -X GET https://emailserver.miltonjunior.dev.br/api/v1/providers \
  -H "x-api-key: pk_sua_chave_publica.sk_sua_chave_secreta"

Enviar E-mail

POST/api/v1/email/send

Parâmetros da Requisição

CampoTipoObrigatórioDescrição
providerIdstringSimID do provedor SMTP configurado
tostring[]SimArray de e-mails dos destinatários
subjectstringSimAssunto do e-mail
htmlstringSimCorpo do e-mail em HTML
textstringNãoVersão em texto simples
fromstringNãoNome e e-mail do remetente
replyTostringNãoE-mail para responder (Reply-To)
ccstring[]NãoCópia do e-mail
bccstring[]NãoCópia oculta
metadataobjectNãoDados customizados para rastreamento

Exemplo Completo

curl -X POST https://emailserver.miltonjunior.dev.br/api/v1/email/send \
  -H "x-api-key: pk_abc123.sk_secret456" \
  -H "Content-Type: application/json" \
  -d '{
    "providerId": "674c5a1b2e8f9a3d4e5f6a7b",
    "to": ["cliente@exemplo.com", "suporte@exemplo.com"],
    "cc": ["gerente@exemplo.com"],
    "subject": "Confirmação de Pedido #12345",
    "from": "Loja Virtual <noreply@lojavirtual.com>",
    "replyTo": "atendimento@lojavirtual.com",
    "html": "<div><h1>Obrigado pelo seu pedido!</h1><p>Seu pedido #12345 foi confirmado e será enviado em breve.</p></div>",
    "text": "Obrigado pelo seu pedido! Seu pedido #12345 foi confirmado e será enviado em breve.",
    "metadata": {
      "orderId": "12345",
      "customerId": "67890",
      "campaign": "black-friday-2025"
    }
  }'

Resposta de Sucesso (200 OK)

{
  "id": "674c5f8d3a1b2c3d4e5f6a8c",
  "status": "queued"
}

O e-mail foi enfileirado e será processado em segundo plano. Use o idretornado para consultar o status do envio.

Consultar Status do E-mail

GET/api/v1/email/:id

Exemplo de Requisição

curl -X GET https://emailserver.miltonjunior.dev.br/api/v1/email/674c5f8d3a1b2c3d4e5f6a8c \
  -H "x-api-key: pk_abc123.sk_secret456"

Resposta (200 OK)

{
  "id": "674c5f8d3a1b2c3d4e5f6a8c",
  "status": "sent",
  "from": "Loja Virtual <noreply@lojavirtual.com>",
  "to": ["cliente@exemplo.com"],
  "cc": ["gerente@exemplo.com"],
  "subject": "Confirmação de Pedido #12345",
  "queuedAt": "2025-11-30T14:30:00.000Z",
  "sentAt": "2025-11-30T14:30:03.521Z",
  "providerMessageId": "<abc123xyz@smtp.gmail.com>",
  "retryCount": 0,
  "error": null,
  "metadata": {
    "orderId": "12345",
    "customerId": "67890",
    "campaign": "black-friday-2025"
  }
}

Status Possíveis

queuedE-mail na fila, aguardando processamento
sendingE-mail sendo enviado no momento
sentE-mail enviado com sucesso
deferredFalha temporária, será retentado automaticamente
failedFalha permanente, não será retentado

Webhooks

Configure webhooks para receber notificações em tempo real sobre o status dos e-mails enviados. Disponível em breve.

Em Desenvolvimento: A funcionalidade de webhooks está sendo implementada e estará disponível em breve.

Limites de Taxa

Para garantir estabilidade e qualidade do serviço, aplicamos os seguintes limites por usuário:

JanelaLimiteDetalhes
Por minuto20 e-mails/minReset a cada 60 segundos
Por hora100 e-mails/hReset a cada 60 minutos
Por dia500 e-mails/diaReset à meia-noite UTC
Destinatários por e-mailaté 50 endereçosEntre to, cc e bcc combinados
Tamanho máx. de anexo2 MB por arquivoMáximo de 5 anexos por envio
Tentativas de reenvioaté 5 tentativasBackoff exponencial automático

Nota: Se você exceder os limites, receberá uma resposta 429 Too Many Requests. Aguarde e tente novamente após o período de reset.

Precisa de limites maiores?

Os limites são configurados pelo administrador da instância. Se você hospeda sua própria instância, ajuste as configurações no painel de admin.

Ver opções →

Códigos de Resposta HTTP

CódigoDescrição
200 OKRequisição processada com sucesso.
400 Bad RequestDados inválidos (e-mail malformado, campos obrigatórios faltando, etc).
401 UnauthorizedChave de API inválida, ausente ou expirada.
404 Not FoundRecurso não encontrado (e-mail ID inexistente, etc).
429 Too Many RequestsLimite de taxa excedido. Aguarde antes de tentar novamente.
500 Server ErrorErro interno do servidor. Tente novamente mais tarde.
502 Bad GatewayFalha ao comunicar com o provedor SMTP.

Pronto para Começar?

Crie sua conta gratuita e comece a enviar e-mails transacionais em minutos.

Criar Conta Grátis