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 a estabilidade e qualidade do serviço, aplicamos os seguintes limites:

Plano Gratuito

  • • 100 e-mails por hora
  • • 1.000 e-mails por dia
  • • 10.000 e-mails por mês

Precisa de Mais?

Entre em contato para planos personalizados ou hospede sua própria instância (código aberto).

Ver opções →

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

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