SMTP e IMAP com senhas de app

Conectar clientes de e-mail e sistemas legados por SMTP e IMAP com senhas de aplicativo: hosts, portas, autoconfig.

SMTP e IMAP (clientes de e-mail)

Este guia mostra como usar uma caixa do Asender Mail num cliente de e-mail (Thunderbird, Apple Mail, Outlook, celular) ou em código, por IMAP (ler) e SMTP de submissão (enviar), em vez de usar o webmail ou a API HTTP.

Disponibilidade: em implantação. O gateway de IMAP/SMTP está construído e testado, mas ainda não está liberado ao público: o serviço só é ligado nas máquinas em que a operação o declara, e a autoconfiguração (autoconfig e registros SRV no DNS) depende desse mesmo passo. Os endereços, portas e comportamentos abaixo são os definidos no código, mas não configure clientes de produção até este aviso sair deste guia. Para enviar e-mail agora, use a API de envio.

Resumo

Fatos que evitam tentativa e erro:

• A senha da conta não funciona aqui. O gateway só aceita senha de aplicativo (próxima seção). Cada aplicativo tem a sua e você revoga uma sem afetar as outras.
• Não há texto puro nem POP3. Não existe IMAP na 143, e o AUTH sequer é oferecido antes do TLS. No 587 o STARTTLS é obrigatório antes do login. A versão mínima do TLS é a 1.2.
• Os servidores são os mesmos para todos os domínios. Mesmo que o seu e-mail seja voce@seudominio.com.br, o servidor é imap.asender.com.br / smtp.asender.com.br (e não imap.seudominio.com.br). Para confirmar os nomes, veja os registros SRV do seu domínio: dig +short SRV _imaps._tcp.seudominio.com.br.
• Só para caixas hospedadas no Asender Mail. Se o seu domínio usa o Asender apenas para enviar (o recebimento é do Google Workspace ou do Microsoft 365), não há caixa aqui — use o cliente do seu provedor de recebimento.

1. Crie uma senha de aplicativo

A senha de aplicativo é uma credencial própria para o programa de e-mail, no lugar da senha da conta.

1. Entre em https://auth.asender.net e abra Minha conta → Dispositivos (https://auth.asender.net/conta/dispositivos).
2. Na seção Senhas de aplicativo, clique em Criar senha.
3. Dê um nome ao aplicativo (por exemplo, "Thunderbird no notebook", até 60 caracteres) e marque o que ele pode fazer: Ler e organizar e-mails (IMAP), que dá o escopo mail:imap, e/ou Enviar e-mails (SMTP), que dá o escopo mail:smtp.
4. Confirme com o seu segundo fator, se for pedido (a criação exige reautenticação).
5. Copie a senha agora. Ela aparece uma única vez; depois só é possível criar outra. O formato é asp_ seguido de dois blocos (asp_XXXXXXXX_…).

Regras:

• Marque só os escopos de que o aplicativo precisa. Uma senha com mail:imap não consegue enviar, e uma com mail:smtp não consegue ler. Um cliente de e-mail completo precisa dos dois escopos (pode ser uma senha só, com os dois).
• O limite é de 20 senhas de aplicativo vivas por usuário. A emissão atual não define validade: a senha vale até você revogá-la.
• Revogue uma senha na mesma lista, em Revogar; ela deixa de funcionar imediatamente. Elas também são todas revogadas quando a senha ou o segundo fator da conta são redefinidos ou a conta é excluída; uma conta suspensa não consegue usá-las.
• Uma senha de aplicativo não cria outras nem serve de sessão da conta: ela só abre IMAP/SMTP.
• Guarde-a como um segredo: cofre de senhas do cliente de e-mail, variável de ambiente do servidor; nunca em repositório, navegador ou log.

2. Configuração automática

Thunderbird

O Thunderbird procura https://autoconfig.<domínio-do-e-mail>/mail/config-v1.1.xml. Para o seu domínio responder, é preciso este registro DNS (e o domínio verificado no Asender):

autoconfig.seudominio.com.br.   CNAME   autoconfig.asender.com.br.

O Asender responde 200 com um XML que aponta o IMAP para imap.asender.com.br:993 (SSL) e o SMTP para smtp.asender.com.br:465 (SSL), com usuário %EMAILADDRESS%:

<?xml version="1.0" encoding="UTF-8"?>
<clientConfig version="1.1">
  <emailProvider id="seudominio.com.br">
    <domain>seudominio.com.br</domain>
    <displayName>Asender E-mail (seudominio.com.br)</displayName>
    <displayShortName>Asender</displayShortName>
    <incomingServer type="imap">
      <hostname>imap.asender.com.br</hostname>
      <port>993</port>
      <socketType>SSL</socketType>
      <authentication>password-cleartext</authentication>
      <username>%EMAILADDRESS%</username>
    </incomingServer>
    <outgoingServer type="smtp">
      <hostname>smtp.asender.com.br</hostname>
      <port>465</port>
      <socketType>SSL</socketType>
      <authentication>password-cleartext</authentication>
      <username>%EMAILADDRESS%</username>
    </outgoingServer>
  </emailProvider>
</clientConfig>

("password-cleartext" é o nome que o Thunderbird dá à senha enviada dentro do TLS; a conexão é sempre criptografada.) Detalhes do comportamento da rota:

• Responde só para domínio existente e verificado no Asender; qualquer outro caso (domínio inexistente, não verificado, formato inválido) devolve o mesmo 404, sem dizer qual.
• Também aceita o endereço na consulta: https://autoconfig.asender.com.br/autoconfig/mail/config-v1.1.xml?emailaddress=voce@seudominio.com.br.
• O limite é de 60 consultas por minuto por IP (acima disso, 429 com Retry-After: 60). A resposta pode ser guardada em cache por 1 hora.
• O cliente de e-mail pode tentar o endereço em HTTP antes de HTTPS; a rota responde nos dois.

Registros SRV (RFC 6186)

Para clientes que descobrem servidores por SRV, o grupo "Clientes de e-mail (IMAP/SMTP)" do domínio publica:

_imaps._tcp.seudominio.com.br.         SRV  0 1 993  imap.asender.com.br.
_submissions._tcp.seudominio.com.br.   SRV  0 1 465  smtp.asender.com.br.
_submission._tcp.seudominio.com.br.    SRV  0 1 587  smtp.asender.com.br.

Em Admin → Domínios do painel, o card "Clientes de e-mail (IMAP/SMTP)" mostra se o grupo está publicado e oferece aplicá-lo (na Cloudflare) ou ver os registros para publicar à mão. Ele é opcional: não bloqueia a verificação do domínio, e a configuração manual continua valendo.

Apple Mail e Outlook

• Outlook (Autodiscover): ainda não disponível. Não existe o endpoint de Autodiscover; no Outlook, configure manualmente (próxima seção).
• Apple Mail: não usa o autoconfig do Thunderbird. Os registros SRV acima seguem o padrão que alguns clientes usam, mas não conte com a descoberta automática: configure manualmente.

3. Configuração manual, passo a passo

Os nomes dos menus mudam entre versões; o que importa são os valores.

Thunderbird

1. Conta → Configurar conta de e-mail e informe nome, endereço (voce@seudominio.com.br) e a senha de aplicativo.
2. Se o autoconfig não responder, clique em Configuração manual. Em Entrada, escolha o protocolo IMAP, servidor imap.asender.com.br, porta 993, segurança SSL/TLS e autenticação Senha normal. Em Saída, servidor smtp.asender.com.br, porta 465 com SSL/TLS (ou 587 com STARTTLS) e autenticação Senha normal. O nome de usuário, nos dois, é o endereço completo.
3. Para ler e enviar, a senha de aplicativo precisa ter os dois escopos (ou crie duas senhas e informe cada uma no seu servidor).

Apple Mail (macOS e iOS)

1. Ajustes → Contas de Internet → Adicionar Conta → Outra e escolha Conta de e-mail. Informe nome, endereço e a senha de aplicativo.
2. Quando a configuração automática falhar, escolha Configuração manual com tipo de conta IMAP. Servidor de entrada: imap.asender.com.br (porta 993, SSL ligado). Servidor de saída: smtp.asender.com.br (porta 465 com SSL, ou 587 com STARTTLS). Usuário: o endereço completo; senha: a senha de aplicativo.
3. Em Avançado, confira que Usar SSL está ligado e a autenticação é Senha.

Outlook (versão clássica para Windows)

1. Arquivo → Adicionar Conta, digite o endereço, abra Opções avançadas e marque Permitir configurar manualmente minha conta, escolhendo IMAP.
2. Em Entrada, informe imap.asender.com.br, porta 993, método de criptografia SSL/TLS. Em Saída, smtp.asender.com.br, porta 465 com SSL/TLS (ou 587 com STARTTLS).
3. Quando pedir a senha, use a senha de aplicativo.

Celular (Android e iOS)

Adicione uma conta "Outro/IMAP" com os mesmos valores: IMAP imap.asender.com.br 993 SSL, SMTP smtp.asender.com.br 465 SSL (ou 587 STARTTLS), usuário igual ao endereço, senha de aplicativo.

4. Configuração por código

Em todos os exemplos, o usuário é o endereço completo da caixa, a senha é a senha de aplicativo e o From tem de ser a própria caixa ou uma identidade ("enviar como") dela — veja Regras de envio.

Node.js (Nodemailer)

import nodemailer from "nodemailer";

const transporte = nodemailer.createTransport({
  host: "smtp.asender.com.br",
  port: 465,
  secure: true, // TLS implícito; para a 587 use port: 587, secure: false, requireTLS: true
  auth: { user: process.env.SMTP_USUARIO, pass: process.env.SMTP_SENHA_APP },
});

const info = await transporte.sendMail({
  from: process.env.SMTP_USUARIO, // a própria caixa, ex.: voce@seudominio.com.br
  to: "cliente@exemplo.test",
  subject: "Proposta comercial",
  text: "Olá, segue a proposta que conversamos.",
});
console.log("aceita:", info.messageId);

Python (smtplib e imaplib)

Envio:

import os
import smtplib
import ssl
from email.message import EmailMessage

msg = EmailMessage()
msg["From"] = os.environ["SMTP_USUARIO"]  # a própria caixa
msg["To"] = "cliente@exemplo.test"
msg["Subject"] = "Proposta comercial"
msg.set_content("Olá, segue a proposta que conversamos.")

contexto = ssl.create_default_context()  # valida o certificado e o nome do servidor
with smtplib.SMTP_SSL("smtp.asender.com.br", 465, context=contexto, timeout=60) as s:
    s.login(os.environ["SMTP_USUARIO"], os.environ["SMTP_SENHA_APP"])
    s.send_message(msg)

# Alternativa na 587 (STARTTLS obrigatório antes do login):
# with smtplib.SMTP("smtp.asender.com.br", 587, timeout=60) as s:
#     s.starttls(context=contexto)
#     s.login(...)
#     s.send_message(msg)

Leitura (IMAP):

import imaplib
import os

with imaplib.IMAP4_SSL("imap.asender.com.br", 993) as c:
    c.login(os.environ["SMTP_USUARIO"], os.environ["SMTP_SENHA_APP"])
    c.select("INBOX", readonly=True)
    _, dados = c.search(None, "UNSEEN")
    for num in dados[0].split()[:10]:
        _, partes = c.fetch(num, "(BODY.PEEK[HEADER.FIELDS (FROM SUBJECT)])")
        print(partes[0][1].decode("utf-8", "replace"))

PHP (PHPMailer)

<?php
use PHPMailer\PHPMailer\PHPMailer;
use PHPMailer\PHPMailer\Exception;

require 'vendor/autoload.php'; // composer require phpmailer/phpmailer

$mail = new PHPMailer(true);
try {
    $mail->isSMTP();
    $mail->Host       = 'smtp.asender.com.br';
    $mail->SMTPAuth   = true;
    $mail->Username   = getenv('SMTP_USUARIO');   // endereço completo da caixa
    $mail->Password   = getenv('SMTP_SENHA_APP'); // senha de aplicativo
    $mail->SMTPSecure = PHPMailer::ENCRYPTION_SMTPS; // 465; para a 587: ENCRYPTION_STARTTLS e Port = 587
    $mail->Port       = 465;
    $mail->CharSet    = 'UTF-8';

    $mail->setFrom(getenv('SMTP_USUARIO'));
    $mail->addAddress('cliente@exemplo.test');
    $mail->Subject = 'Proposta comercial';
    $mail->Body    = 'Olá, segue a proposta que conversamos.';
    $mail->send();
} catch (Exception $e) {
    error_log('falha no envio: ' . $mail->ErrorInfo);
}

Use sempre destinatários de teste (@exemplo.test, .invalid, .example) em ambientes que não sejam de produção. Fora de produção, um destinatário real faz o envio ser recusado de propósito.

Regras de envio

O SMTP do Asender é uma submissão autenticada: ele recebe a mensagem pronta do seu cliente, confere se você pode enviá-la e a entrega ao serviço de envio do Asender, que assina o e-mail com o DKIM do seu domínio e o despacha. Por isso:

• Remetente. O endereço do MAIL FROM (e o cabeçalho From, que precisa ser igual a ele) tem de ser a caixa autenticada ou uma identidade ("enviar como") dela. Qualquer outro remetente é recusado com 553 5.7.1; um From diferente do envelope é recusado com 550 5.7.1. O domínio do remetente precisa estar verificado no Asender, com o DKIM conferido.
• Cópia em Enviados. O envio por SMTP não grava a mensagem na pasta Enviados. Quem salva a cópia é o cliente de e-mail, por um APPEND por IMAP — o que Thunderbird, Apple Mail e Outlook fazem sozinhos. Em código, você mesmo precisa fazer o APPEND se quiser a cópia.
• Cópia oculta. Os destinatários em Cco são entregues e removidos do cabeçalho da mensagem que chega aos demais.
• Quota do plano. Cada destinatário (Para, Cc e Cco) consome um envio da quota do plano. Ao estourar o teto, o SMTP responde 452 4.2.2 (cota de envio esgotada, tente de novo mais tarde).
• Supressão. Destinatário em supressão global (bounce permanente, reclamação) é recusado já no RCPT TO com 550 5.1.1.
• Antivírus. Anexo infectado recusa a mensagem inteira (554 5.7.0).

Limites

O gateway SMTP não aplica, no seu próprio código, um limite de mensagens por minuto; o teto de envio é a quota do plano (acima) e o limite de conexões por IP.

O que o IMAP oferece

IMAP4rev1 com IDLE (notificação de novas mensagens), UIDPLUS, MOVE, SPECIAL-USE, NAMESPACE, CHILDREN, ESEARCH, LIST-EXTENDED, LIST-STATUS, LITERAL+ e APPENDLIMIT. Não há CONDSTORE/QRESYNC nem IMAP4rev2.

As pastas padrão da caixa são Entrada (INBOX), Enviados, Rascunhos, Arquivo, Spam e Lixeira, e o servidor as marca com SPECIAL-USE (\Sent, \Drafts, \Archive, \Junk, \Trash); use o atributo, e não o nome, para descobrir qual é qual. A quarentena de segurança nunca aparece no IMAP.

Mensagens de erro comuns

SMTP ou API de envio: quando usar cada um

Regra prática: código seu enviando mensagens de sistema usa a API (chave de API, idempotência, resposta estruturada, 202 imediato). Uma pessoa usando uma caixa — ou um software que só sabe SMTP — usa o SMTP com a senha de aplicativo dela. Detalhes das APIs: Mail API e Plataforma.