Autenticação

Todas as requisições à API do FlowMail devem ser autenticadas via header HTTP. A autenticação é feita através de API Keys, que podem ser gerenciadas no painel do dashboard.

Header de Autenticação

Inclua o header Authorization em todas as requisições, usando o esquema Bearer seguido da sua API key.

Header HTTP

Authorization: Bearer fm_live_aBcDeFgHiJkLmNoPqRsTuVwXyZ012345

Tipos de Chave

O FlowMail utiliza dois tipos de API key, diferenciados pelo prefixo. Isso permite identificar facilmente o ambiente de cada chave.

Prefixo	Ambiente	Descrição
`fm_live_`	Produção	Chave para uso em ambiente de produção. As verificações consomem créditos do seu plano e os resultados são definitivos.
`fm_test_`	Teste	Chave para desenvolvimento e testes. As verificações retornam resultados simulados e não consomem créditos.

Exemplo Completo

Uma requisição autenticada para verificar um email:

cURL

curl -X POST https://mail.flowsales.online/api/v1/verify \
  -H "Authorization: Bearer fm_live_aBcDeFgHiJkLmNoPqRsTuVwXyZ012345" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"email": "contato@empresa.com.br"}'

Erros de Autenticação

Quando a autenticação falha, a API retorna um status HTTP 401 Unauthorized. Veja os cenários mais comuns:

Chave ausente

O header Authorization não foi enviado na requisição.

JSON — 401 Unauthorized

{
  "error": {
    "code": "auth_missing",
    "message": "API key não fornecida. Inclua o header Authorization: Bearer {API_KEY}."
  }
}

Chave inválida ou revogada

A API key enviada não é reconhecida ou foi revogada no dashboard.

JSON — 401 Unauthorized

{
  "error": {
    "code": "auth_invalid",
    "message": "API key inválida ou revogada. Verifique sua chave no dashboard."
  }
}

Segurança das Chaves

O FlowMail adota práticas rigorosas para proteger suas API keys:

Hash SHA-256: as chaves são armazenadas como hash irreversível (SHA-256). Mesmo em caso de vazamento de dados, as chaves originais não podem ser recuperadas.

Exibição única: a chave completa é exibida apenas no momento da criação. Depois disso, somente os últimos 8 caracteres ficam visíveis no dashboard.

Revogação instantânea: ao revogar uma chave no dashboard, ela é invalidada imediatamente. Nenhuma requisição posterior será aceita.

Boas práticas

Nunca inclua API keys diretamente no código-fonte. Utilize variáveis de ambiente (FLOWMAIL_API_KEY) e configure-as no servidor ou no seu gerenciador de secrets.