Enviar e-mail por SMTP

Se sua aplicação já suporta SMTP, aponte-a para nosso relay alterando host, porta e credenciais. Frameworks, sistemas de gerenciamento de conteúdo, impressoras e outros softwares que podem enviar e-mail para um relay SMTP podem usar esse caminho.

E-mails enviados por SMTP são tratados exatamente como e-mails enviados pela API de e-mail: a mesma verificação de domínio, pools de IP, assinatura DKIM, tratamento de supressões, rastreamento, eventos e analytics. SMTP é uma segunda entrada para o mesmo produto, então tudo que você configurar para um se aplica ao outro.

Escolha o serviço de relay SMTP quando quiser manter o código de construção de mensagens existente da sua aplicação. Escolha a API de e-mail quando precisar de campos estruturados na solicitação ou de templates armazenados. SMTP obtém o conteúdo da mensagem MIME e as opções de envio da configuração da chave API.

O que você precisa antes

Um domínio de envio verificado. O endereço que você coloca em MAIL FROM (e no cabeçalho From da mensagem) deve pertencer a um domínio verificado neste espaço de trabalho. Consulte Domínios de envio.
Uma chave API com o escopo emails. SMTP usa suas chaves API normais e não exige uma credencial SMTP separada. Crie uma chave em Developers > Chaves API com envio de e-mail habilitado. Uma chave sem o escopo emails não pode enviar, assim como uma chave somente verify.

Configurações de conexão

Aponte seu cliente para o host SMTP da região da sua chave. A região é o prefixo na própria chave: uma chave bk_eu1_... envia pelo host eu1, uma chave bk_us1_... pelo us1. Autenticar com uma chave da outra região falha com uma resposta 535 indicando o host correto.

Região	Host
EU	eu1.smtp.bird.com
US	us1.smtp.bird.com

Porta	Criptografia
465	TLS implícito (SMTPS)
587	STARTTLS
2525	STARTTLS

Use a que seu cliente suportar:

Porta 465, TLS implícito (SMTPS). A conexão é criptografada desde o primeiro byte, antes de qualquer comando ser enviado. Na maioria das bibliotecas, essa é a opção "SSL/TLS" ou "SMTPS".
Portas 587 e 2525, STARTTLS. A conexão começa em texto plano e é atualizada para TLS com o comando STARTTLS antes da autenticação. Essa é a opção "STARTTLS", às vezes rotulada simplesmente como "TLS". Use 2525 se sua rede bloquear a 587.

De qualquer forma, a sessão é criptografada antes de suas credenciais serem enviadas, então elas nunca trafegam em texto claro: nas portas 587 e 2525, AUTH é recusado até que STARTTLS tenha sido executado. A porta 25 não é oferecida para envio.

Autenticação

Autentique com AUTH PLAIN ou AUTH LOGIN. O nome de usuário é a string literal bird, e a senha é sua chave API:

Exemplo de código

Username: bird
Password: bk_eu1_your_api_key

O nome de usuário é um literal fixo e não tem identidade própria. A chave API no campo de senha é o que autentica. Na maioria das ferramentas SMTP, você cola sua chave API no campo de senha e define o nome de usuário como bird. Revogar a chave interrompe o envio SMTP em segundos, inclusive no meio de uma conexão.

O que vem da mensagem e o que vem da configuração da chave

Tudo que tem um lugar natural em uma mensagem MIME vem da própria mensagem: os cabeçalhos From, To, Cc e Reply-To, o assunto, os corpos HTML e texto, além de anexos e imagens inline. Os destinatários são obtidos do envelope SMTP (RCPT TO). Um endereço em RCPT TO que não está em um cabeçalho visível To ou Cc é tratado como Bcc. Uma mensagem pode ter no máximo 50 destinatários entre to, cc e bcc, e o tamanho total da mensagem é limitado a 20 MB.

Opções de envio que não têm um lugar padrão em uma mensagem MIME vêm da configuração SMTP da chave. Isso inclui o pool de IP, categoria, tags e rastreamento de abertura e clique. Uma chave não configurada usa o pool padrão da organização, a categoria transactional e rastreamento habilitado. Configure a chave em Email > SMTP, ou chame a SMTP config API. Dê a cada aplicação sua própria chave quando ela precisar de padrões diferentes. As alterações se aplicam a novas mensagens sem reconectar o cliente.

Uma sessão completa

Na porta 465, o cliente abre a conexão TLS primeiro e depois executa todo o diálogo SMTP dentro dela:

Exemplo de código

   ... TLS handshake ...
S: 220 eu1.smtp.bird.com ESMTP Service Ready
C: EHLO myapp
S: 250-Hello myapp
   250-PIPELINING
   250-8BITMIME
   250-ENHANCEDSTATUSCODES
   250-CHUNKING
   250-AUTH PLAIN LOGIN
   250-SIZE 20971520
   250 LIMITS RCPTMAX=50
C: AUTH PLAIN <base64 of bird + key>
S: 235 2.0.0 Authentication succeeded
C: MAIL FROM:<news@yourdomain.com>
C: RCPT TO:<delivered@messagebird.dev>
C: DATA
   ... your MIME message ...
C: .
S: 250 2.0.0 Ok: queued as em_01ky7ma8y2es1s2akzk53tmjn0

Na porta 587 ou 2525, o cliente conecta em texto plano, emite STARTTLS para atualizar a conexão e depois executa o mesmo diálogo dentro de TLS. AUTH não é oferecido até que a atualização seja concluída:

Exemplo de código

S: 220 eu1.smtp.bird.com ESMTP Service Ready
C: EHLO myapp
S: 250-Hello myapp
   250-PIPELINING
   250-8BITMIME
   250-ENHANCEDSTATUSCODES
   250-CHUNKING
   250-STARTTLS
   250-SIZE 20971520
   250 LIMITS RCPTMAX=50
C: STARTTLS
S: 220 2.0.0 Ready to start TLS
   ... TLS handshake ...
C: EHLO myapp
S: 250-Hello myapp
   250-PIPELINING
   250-8BITMIME
   250-ENHANCEDSTATUSCODES
   250-CHUNKING
   250-AUTH PLAIN LOGIN
   250-SIZE 20971520
   250 LIMITS RCPTMAX=50
C: AUTH PLAIN <base64 of bird + key>
S: 235 2.0.0 Authentication succeeded
C: MAIL FROM:<news@yourdomain.com>
C: RCPT TO:<delivered@messagebird.dev>
C: DATA
   ... your MIME message ...
C: .
S: 250 2.0.0 Ok: queued as em_01ky7ma8y2es1s2akzk53tmjn0

O 250 final retorna o ID da mensagem enfileirada, o mesmo ID em_... que você obteria da API. Você pode buscar a mensagem por esse ID no Log de e-mail ou por GET /v1/email/messages/{message_id}.

Tentando novamente com segurança

O pipeline aceita uma mensagem e a entrega de forma assíncrona, e clientes SMTP fazem retentativas agressivas quando uma conexão cai. Para tornar uma retentativa segura, adicione um cabeçalho X-Bird-Idempotency-Key à mensagem: uma repetição dentro da janela de retenção retorna o ID da mensagem já enfileirada em vez de enviar uma segunda cópia. Use um valor estável para a mensagem lógica, como um ID de pedido ou ID de notificação. Evite gerar um valor aleatório para cada tentativa.

Mantenha o ID da mensagem enfileirada junto com o evento da aplicação que causou o envio. Se a conexão cair antes de você receber a resposta final, tente novamente essa mensagem lógica com a mesma chave. Após a janela de retenção, uma retentativa pode criar outra mensagem. Preserve seu próprio registro de envio para recuperação além dessa janela.

Limites de conexão

Cada organização pode manter até 10 conexões SMTP autenticadas simultâneas por padrão. Uma conexão conta da autenticação até o fechamento, em todos os servidores e chaves API da organização. No limite, outra conexão recebe uma resposta transiente 421 após a autenticação. Reutilize conexões, reduza a concorrência e tente novamente. O limite conta conexões abertas independentemente do volume de mensagens. Email > SMTP mostra as conexões ativas em relação ao limite.

Dimensione seu pool de conexões de acordo com o limite de conexões da organização. Controle o ritmo de envios conforme as cotas de envio. Os cabeçalhos de limitação de requisições HTTP descrevem solicitações API; eles não são uma permissão de taxa de envio SMTP.

Tratar respostas SMTP

SMTP reporta um domínio de envio não verificado, domínio de destinatário reservado, pool de IP inutilizável, tipo de anexo bloqueado ou mensagem malformada com uma resposta permanente 550. Uma mensagem acima do limite de 20 MB retorna 552. Uma cota de envio excedida ou contagem de destinatários acima de 50 retorna uma resposta transiente 452. Destinatários suprimidos são tratados de forma assíncrona: SMTP aceita a mensagem e cada destinatário suprimido aparece como rejected no log de e-mail e nos eventos.

Para a decisão de interface, compare envio e recuperação por SMTP e HTTP. Ambos os caminhos enfileiram o trabalho antes da entrega ao destinatário. Um evento email.delivered registra a aceitação pelo servidor de destino. Esse evento não confirma a chegada à caixa de entrada.

Próximos passos

Domínios de envio: verifique o domínio pelo qual você vai enviar.
IPs dedicados e pools: escolha de qual pool uma chave envia.
Supressões: por que um destinatário aceito pode não receber uma mensagem.
Log de e-mail: encontre uma mensagem pelo ID que SMTP retornou.

Recursos relacionados

Continue com a documentação, guias e exemplos sobre este tópico. Os recursos estão em inglês.

Explore a funcionalidadeSMTP relay