HuSend Docs

Integração pública da HuSend

Portal oficial para integrar a HuSend em produção com API REST, SMTP autenticado e autenticação de domínio.

Abrir API Ver status
Base da API https://api.husend.com/api/v1

Ambiente público de produção.

Host SMTP mail.husend.com

Mesma identidade técnica usada no envio autenticado.

Comece aqui

Visão geral da plataforma

A HuSend expõe um ambiente público de produção para envio de e-mails via API REST e SMTP autenticado. Este portal centraliza endpoints, autenticação, formatos de payload, DNS obrigatório, limites e os principais códigos de resposta para colocar sua integração no ar com menos atrito.

O que existe hoje

  • Envio JSON via POST /send/message
  • Envio RFC822/MIME via POST /send/raw
  • Consulta via GET /messages/{id}
  • SMTP autenticado em produção

Domínios públicos

  • https://husend.com
  • https://app.husend.com
  • https://api.husend.com
  • https://status.husend.com
Ambiente oficial

Produção e ambientes

A HuSend publica hoje um ambiente único de produção. Para novas integrações, a recomendação é começar com destinatários internos, domínio autenticado e monitoramento ativo antes de ampliar volume.

API REST https://api.husend.com/api/v1
SMTP mail.husend.com
Status https://status.husend.com
Boa prática: trate esse ambiente como produção desde o primeiro dia: use HTTPS, segmente destinatários de prova, valide SPF/DKIM/DMARC e monitore rejeições por provider.
Controle de acesso

Autenticação

Toda chamada de envio ou consulta deve ser autenticada. A forma principal é o header X-Server-API-Key. Também existe suporte a Basic Auth para integrações legadas e ferramentas de linha de comando.

Header dedicado

Basic Auth

Endpoint principal

Envio via API

O endpoint POST /send/message aceita payload JSON e é o caminho padrão para envio transacional. Os campos mínimos são destinatário, remetente, assunto e corpo em texto ou HTML. O campo from precisa usar um domínio autenticado e liberado para o cliente.

Campos principais

  • to ou recipients
  • from
  • subject
  • plain_body e/ou html_body
  • reply_to, headers e envelope_sender quando necessário

Resposta

  • status
  • time
  • data.message_id
  • data.messages[destinatario]

Resposta de sucesso

MIME avançado

Envio RAW / RFC822

Use POST /send/raw quando você precisa enviar a mensagem completa em RFC822/MIME. Esse é o caminho ideal para layouts já montados por outra biblioteca ou mensagens com cabeçalhos e partes MIME controladas.

Dica prática: se você precisa de anexos ou MIME customizado, prefira esse endpoint em vez de tentar estender o payload JSON.

Exemplo cURL

Observabilidade

Consulta de mensagem

Depois do envio, a HuSend devolve identificadores de rastreio. Use o request_id retornado pela API e, quando aplicável, o message_id informado no resultado para recuperar o status do envio e o mapa por destinatário.

GET /messages/{id}

Envio por SMTP

SMTP autenticado

O SMTP público da HuSend usa autenticação PLAIN / LOGIN e a mesma identidade técnica da API. O host oficial é mail.husend.com.

Entregabilidade

DNS e autenticação do domínio

SPF, DKIM e DMARC são obrigatórios para manter a reputação do envio e evitar pausa automática por DNS. A HuSend também usa um host SMTP dedicado com A e PTR alinhados.

Identificação SPF: quando sua política central estiver consolidada em outro domínio, inclua include:spf2.homemurbano.com.br no SPF publicado e peça a liberação dos IPs 204.168.248.121 e 95.216.181.245 no gateway, antispam ou provedor responsável pela validação de saída.

SPF

DKIM

DMARC

A / PTR / MX

Respostas e políticas

Limites e erros HTTP

A API responde com mensagens claras para bloqueio de domínio, DNS obrigatório, supressão definitiva, limite horário e problemas de relay. Use esses códigos para governar retry, pausa e observabilidade.

Status Quando acontece Tratamento recomendado
200 Envio aceito com sucesso ou parcialmente aceito. Persistir message_id e acompanhar o resultado por destinatário.
400 Payload inválido, campo ausente ou corpo malformado. Corrigir o JSON/RFC822 antes de reenviar.
401 API key ou Basic Auth inválidos. Revalidar credenciais e headers enviados.
404 Rota inexistente ou mensagem não encontrada. Verificar endpoint, método e message_id.
409 Destinatário suprimido por bounce definitivo. Não reenviar até revisar a base de destinatários.
413 Mensagem acima do limite total de conteúdo. Reduzir o payload ou usar MIME mais eficiente.
423 Domínio pausado por ausência de SPF, DKIM ou DMARC. Corrigir DNS e validar o domínio antes de continuar.
429 Limite horário ou cota do cliente atingidos. Aplicar backoff e reprogramar a fila para a próxima janela.
500 Erro interno inesperado. Registrar request id e abrir suporte se persistir.
502 Falha no relay SMTP interno. Verificar status do SMTP e usar status.husend.com.
Governança

API keys, domínios permitidos e segurança

Regras de envio

  • Cada usuário API precisa ter ao menos um domínio permitido.
  • O domínio do remetente visível ou do envelope deve bater com a lista autorizada.
  • Se o DNS do domínio estiver pausado, a API devolve 423.

Boas práticas

  • Use HTTPS em todas as requisições.
  • Armazene a API key em variável de ambiente ou segredo do servidor.
  • Evite client-side público e repositórios com credenciais expostas.
Ajuda operacional

Suporte

Use a página de status para incidentes públicos e o canal de suporte configurado na sua conta para casos específicos de produção. Quando o canal estiver habilitado, o botão de suporte aparece automaticamente no topo desta documentação.

Status recomendado: consulte primeiro https://status.husend.com {" "}antes de abrir um chamado sobre indisponibilidade.
Roadmap público

Em breve

WebHooks

Planejados para eventos de entrega, rejeição e automações externas. Ainda não documentados como recurso ativo.

Repositório público de exemplos

Estrutura prevista para snippets por linguagem e coleções prontas de integração, sem depender do painel autenticado.