Integrações: todos os meios

O mapa de tudo o que dá para integrar com a Asender: API REST, APIs por ferramenta, Entrar com Asender (OAuth), MCP, webhooks, SMTP/IMAP, navegador, DNS, conversões e conectores — quando usar cada um e como autenticar.

Este é o mapa de todos os meios de integrar com a Asender. Para cada um: para que serve, quando usar, como autenticar, onde fica e qual guia aprofunda. Se você ainda não sabe qual usar, vá direto para a tabela de decisão.

A Asender é um conjunto de ferramentas independentes (e-mail, CRM, páginas, mensageria, atendimento) sob uma identidade só. Cada ferramenta tem a API dela num endereço próprio; uma API pública da plataforma reúne o envio de mensagens e a leitura de dados. Uma ferramenta fora do ar não derruba as outras.

Visão rápida

API REST pública

Para que serve. É a porta de integração de máquina da plataforma. Dois grupos de rotas:

• Enviar mensagens, de servidor para servidor: POST /v1/emails/send e /v1/emails/batch (até 500), POST /v1/sms/send, POST /v1/whatsapp/send, POST /v1/push/send, POST /v1/telegram/send, POST /v1/whatsweb/send (WhatsApp pelo aparelho) e POST /v1/telegramconta/send (Telegram pela conta). Também GET /v1/senders (de quais endereços sua chave pode enviar).
• Ler dados da conta: /v1/leads, /v1/forms (e envios), /v1/conversions, /v1/campaigns e /v1/reports/email/*, /v1/messaging/* (SMS, WhatsApp, push), /v1/analytics/*, /v1/conversations, /v1/journeys, mais /v1/emails (histórico), /v1/account, /v1/account/usage e /v1/logs (o log das suas próprias requisições).

Quando usar. Seu backend dispara mensagens transacionais ou de campanha, ou sincroniza leads e métricas para outro sistema.

Autenticação. Authorization: Bearer sk_live_… (produção) ou sk_test_… (teste). Cada chave tem escopos (email:send, sms:send, leads:read, campaigns:read…); rota fora do escopo responde 403. Um app OAuth de terceiro também chama as rotas de leitura, com o consentimento do usuário. A chave nunca vai para o navegador.

curl -X POST 'https://api.asender.net/v1/emails/send' \
  -H 'Authorization: Bearer sk_live_SUA_CHAVE' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: 5b0c4d1e-8a3f-4e7b-9c21-aa17c2f0e001' \
  -d '{
    "Source": "avisos@seudominio.com.br",
    "Destination": { "ToAddresses": ["cliente@example.com"] },
    "Message": { "Subject": { "Data": "Seu código" }, "Body": { "Text": { "Data": "Código: 123456" } } }
  }'

Guias. Referência da Plataforma · Convenções (formato, erros, paginação, idempotência, limites) · Chaves de API e escopos.

API de E-mail

Para que serve. Administrar domínios e caixas de e-mail corporativo, ler e enviar mensagens de uma caixa, rascunhos, contatos e assinatura.

Quando usar. Você precisa enviar a partir de uma caixa que existe (ou construir um cliente de e-mail sobre a plataforma). Para e-mail transacional de qualquer endereço de um domínio verificado (por exemplo, código de verificação), use POST /v1/emails/send da API pública, acima — não exige criar caixa.

Autenticação. API key Authorization: Bearer sk_…. Escopo de administração: mail:admin.

Endereço. https://api.mail.asender.net — envelope de erro { "error", "message" }.

Guias. API de E-mail · Domínios e DNS · SMTP e IMAP.

API do CRM

Para que serve. Contatos, estágios, segmentos, jornadas, alertas e destinos de lead.

Quando usar. Você está construindo uma interface que opera o CRM como usuário logado. A API do CRM é uma superfície de sessão: não aceita API key. Integração máquina-a-máquina com dados de CRM passa pela API pública: leitura de contatos em GET /v1/leads, jornadas em GET /v1/journeys e conversões em GET /v1/conversions, com os escopos leads:read, journeys:read e conversions:read.

Autenticação. Sessão OIDC do usuário (Authorization: Bearer <token>) e o cabeçalho X-Asender-Tenant com a conta em que opera.

Endereço. https://api.crm.asender.net — envelope de erro { "erro": "…" }.

Guia. API do CRM.

API de Páginas

Para que serve. Criar, editar e publicar páginas e formulários, mídia, domínios e redirects; ler a analytics do que foi publicado; enviar leads de um sistema seu para um formulário.

Quando usar. Automatizar a construção de páginas (inclusive por agentes de IA) ou capturar leads de um backend próprio.

Autenticação. Três públicos: sessão do usuário (construtor), API key com escopo (pages:read, pages:write, pages:publish, forms:read, forms:write) para integração de servidor, e credenciais públicas do navegador (formulário embutido, pixel).

Endereço. https://api.pages.asender.net (a página publicada e o runtime ficam em https://sites.asender.net) — envelope de erro { "erro": "…" } na autoria.

Guias. API de Páginas · O JSON do documento v2.

Entrar com Asender (OAuth)

Para que serve. Seu app identifica um usuário Asender e, com o consentimento dele, lê dados da conta pela API pública, com escopos mínimos (somente leitura).

Quando usar. Você tem um produto de terceiro (site, SaaS, ferramenta interna) e quer "Entrar com Asender", ou precisa de acesso delegado a dados de clientes sem pedir a chave de API deles.

Autenticação. Authorization Code com PKCE S256 obrigatório, cliente confidencial (client_secret_basic), redirect_uri exata. Endpoints no discovery: https://auth.asender.net/.well-known/openid-configuration. O token resultante chama a API pública como Authorization: Bearer <access_token>.

Cadastro do app. Você mesmo cadastra e gerencia o app no Portal de Aplicativos do painel (admin.asender.net, em Desenvolvedores > Aplicativos): credenciais, escopos, testadores e pedido de revisão à equipe Asender. O guia de Aplicativos descreve o painel, o ciclo de vida (desenvolvimento, revisão, publicado) e o selo Verificado.

Guias. Entrar com Asender (fluxo completo, erros e exemplo de código) · Identidade (OIDC / OAuth 2.1).

Servidor MCP

Para que serve. Conectar assistentes e agentes de IA (que falam o Model Context Protocol) diretamente à sua conta Asender, como ferramentas.

Quando usar. Você quer que um agente consulte dados ou execute ações sem escrever um cliente HTTP.

Autenticação. OAuth: o cliente MCP se registra sozinho em auth.asender.net (CIMD ou DCR), o usuário autoriza na tela de consentimento e o agente apresenta o token no servidor MCP. Também vale uma chave de API sk_* no header Authorization. O registro automático está em Aplicativos.

Endereço. https://api.asender.net/mcp. Somente leitura nesta fase. Veja o guia de MCP.

Webhooks

Para que serve. A Asender chama o seu endpoint quando algo acontece (um e-mail ou SMS com resultado, um lead novo, uma submissão de formulário, uma entrega do conector), e recebe webhooks de provedores (status de mensagem, pagamento).

Quando usar. Você prefere ser avisado a ficar consultando a API (polling). Para ler o que mudou desde a última vez, combine com updated_after nas rotas de dados da API pública.

Autenticação. Todos os emissores usam o formato Asender Webhook v1: Asender-Signature: t=<unix>,v1=<hex> (HMAC-SHA256 sobre "<t>.<corpo cru>", tolerância de 300 s), mais Asender-Webhook-Id (deduplicação) e Asender-Event. Verifique a assinatura sobre o corpo cru antes de confiar no conteúdo. Os cabeçalhos antigos saem em 2027-04-20. Endpoints de eventos da conta: /v1/webhooks com chave de escopo webhooks:manage.

Guia. Webhooks traz o formato v1, um verificador em Node, Python, Go e PHP, o cadastro de cada emissor, as tentativas e como tratar duplicatas.

SMTP e IMAP

Para que serve. Usar a caixa Asender de um cliente de e-mail (Thunderbird, Outlook, celular) ou enviar de um sistema legado que só fala SMTP.

Quando usar. O software não consegue chamar HTTP, ou o usuário final quer o e-mail no app de sempre.

Autenticação. Senha de aplicativo (uma por dispositivo ou sistema, revogável), nunca a senha da conta. O DNS do domínio publica o autoconfig para que os clientes se configurem sozinhos.

Guia. SMTP e IMAP (hosts, portas, senhas de aplicativo) e Domínios e DNS.

No navegador

Para que serve. O que roda no site do visitante: formulário de captura (embed por <script> ou HTML), pixel de analytics e de conversão, chat, Web Push e o SDK JavaScript @asender/pages-sdk.

Quando usar. Você quer capturar leads, medir visitas ou assinar notificações no seu site, sem backend próprio.

Autenticação. Credenciais públicas, restritas por origem e por escopo mínimo: o token do formulário/pixel (embutido na página) e a chave pk_push_…, que só registra inscrição de Web Push. A chave sk_… nunca vai ao navegador. Para enviar lead de um servidor seu, use a API de Páginas com chave.

Guia. No navegador.

Domínios e DNS

Para que serve. Provar a posse e apontar o seu domínio: SPF, DKIM e DMARC para enviar e-mail; CNAME/A para publicar páginas. O botão "Conectar com Cloudflare" usa Domain Connect e aplica os registros por você, com a sua autorização.

Quando usar. Antes do primeiro envio com o seu domínio, ou ao publicar uma página nele.

Guia. Domínios e DNS.

Conversões e conectores

Para que serve. Devolver conversões de marketing para Meta, Google Ads e TikTok (API de conversão, com deduplicação por eventID) e entregar leads a sistemas externos: Kommo e um destino HTTP próprio.

Quando usar. Você quer otimizar campanhas de anúncio com a conversão real, ou encaminhar cada lead capturado para o seu CRM/ERP.

Autenticação. Credenciais do destino (token do provedor, URL do seu endpoint), cadastradas no painel e guardadas só no servidor.

Guia. Conversões e conectores.

Para agentes de IA

Para que serve. Dar a um agente o contexto completo da API sem ele navegar página a página.

• llms.txt: índice curto, no padrão que os agentes procuram na raiz do domínio.
• llms-full.txt: toda a documentação (guias, operações e schemas) em um arquivo de texto.
• openapi.json e openapi.yaml: OpenAPI 3.1 unificada da API pública; cada API também tem a sua em apis/<api>.openapi.yaml.

Para o agente operar a conta (e não só ler a documentação), use o servidor MCP.

Quero X, use Y

Antes de integrar

• Escolha a credencial mais restrita que resolve. Chave de servidor com o menor conjunto de escopos, ou token OAuth de leitura; nunca a chave no navegador. Ver chaves de API.
• Cada API tem o seu envelope de erro. Não reaproveite o parser de uma em outra: veja as convenções.
• O que está "planejado" ou "em implantação" nesta página ainda não é contrato. Só o que a referência de cada API lista é estável.