Guias

SMTP

Envie pela Postal de qualquer sistema que fale SMTP, usando uma chave de API como senha.

#Configuração

Para sistemas que não falam com APIs (WordPress, ERPs, plataformas de loja, impressoras), use o server SMTP da Postal. Os envios passam pelas mesmas regras da API: domínio verificado, cotas, lista de supressão, e aparecem em E-mails e Logs.

CampoValor
Servidorsmtp.postal.so
Porta465 (TLS direto, recomendada) ou 587 (STARTTLS). Se a rede bloquear essas, use 2465 (TLS) ou 2587 (STARTTLS).
Usuáriopostal
SenhaUma chave de API (ps_…). Uma chave só de envio basta; crie uma exclusiva para o SMTP.
AutenticaçãoAUTH PLAIN ou AUTH LOGIN, sempre depois do TLS.

#Exemplos

SMTP

Node.js

import nodemailer from 'nodemailer';

const transporter = nodemailer.createTransport({
  host: 'smtp.postal.so',
  port: 465,
  secure: true, // TLS direto; para a porta 587 use secure: false
  auth: {
    user: 'postal',
    pass: process.env.POSTAL_API_KEY,
  },
});

const info = await transporter.sendMail({
  from: 'Loja Exemplo <[email protected]>',
  to: '[email protected]',
  subject: 'Seu pedido #10482 saiu para entrega',
  html: '<p>O pedido <b>#10482</b> está a caminho.</p>',
});

console.log(info.response); // 250 2.0.0 OK queued as 019a1b2c-...

Python

import os
import smtplib
from email.message import EmailMessage

message = EmailMessage()
message["From"] = "Loja Exemplo <[email protected]>"
message["To"] = "[email protected]"
message["Subject"] = "Seu pedido #10482 saiu para entrega"
message.set_content("O pedido #10482 está a caminho.")
message.add_alternative("<p>O pedido <b>#10482</b> está a caminho.</p>", subtype="html")

with smtplib.SMTP_SSL("smtp.postal.so", 465) as server:
    server.login("postal", os.environ["POSTAL_API_KEY"])
    server.send_message(message)

PHP

use PHPMailer\PHPMailer\PHPMailer;

$mail = new PHPMailer(true);
$mail->isSMTP();
$mail->Host = 'smtp.postal.so';
$mail->Port = 465;
$mail->SMTPSecure = PHPMailer::ENCRYPTION_SMTPS; // 587: ENCRYPTION_STARTTLS
$mail->SMTPAuth = true;
$mail->Username = 'postal';
$mail->Password = getenv('POSTAL_API_KEY');
$mail->CharSet = 'UTF-8';

$mail->setFrom('[email protected]', 'Loja Exemplo');
$mail->addAddress('[email protected]');
$mail->Subject = 'Seu pedido #10482 saiu para entrega';
$mail->isHTML(true);
$mail->Body = '<p>O pedido <b>#10482</b> está a caminho.</p>';
$mail->send();

Laravel

# .env
MAIL_MAILER=smtp
MAIL_SCHEME=smtps
MAIL_HOST=smtp.postal.so
MAIL_PORT=465
MAIL_USERNAME=postal
MAIL_PASSWORD=ps_sua_chave
[email protected]
MAIL_FROM_NAME="Loja Exemplo"

cURL

curl --ssl-reqd --url "smtps://smtp.postal.so:465" \
  --user "postal:$POSTAL_API_KEY" \
  --mail-from "[email protected]" \
  --mail-rcpt "[email protected]" \
  --upload-file message.eml

#Laravel

Com o .env acima, Mail::to($customer)->send(new OrderShipped($order)) passa a sair pela Postal, sem mudar o código. Na porta 587, use MAIL_SCHEME=smtp e o Laravel ativa o STARTTLS sozinho.

#Como as mensagens são tratadas

  • O remetente vem do cabeçalho From da mensagem, que precisa ser de um domínio verificado (e do domínio da chave, se ela for restrita).
  • Os destinatários são os do envelope (RCPT TO). Quem não aparece em To nem em Cc é tratado como Bcc.
  • A mensagem é enviada como chegou, com anexos e imagens embutidas. Ela fica disponível em GET /emails/{id}/raw.
  • Ao aceitar, o servidor responde 250 2.0.0 OK queued as <id>: o ID é o do e-mail na API.
  • Cada mensagem aparece nos logs com o método SMTP (filtre com source=smtp).
  • Limites: 40 MB por mensagem e 50 destinatários. Sessões ociosas fecham depois de 5 minutos.

#Respostas de erro

CódigoSignificado
535 5.7.8Usuário ou senha errados. O usuário é postal e a senha, a chave de API. Depois de 3 falhas a conexão fecha; muitas falhas do mesmo IP bloqueiam novas tentativas por 10 minutos.
530 5.7.0Faltou autenticar, ou tentou autenticar antes do STARTTLS na porta 587.
550 5.7.1Envio recusado: domínio não verificado, chave restrita a outro domínio ou envios pausados. A mensagem traz o motivo.
550 5.6.0Mensagem inválida (sem From válido, por exemplo).
452 4.5.3Cota diária ou mensal atingida, ou mais de 50 destinatários. É temporário: o cliente pode tentar mais tarde.
552 5.3.4Mensagem maior que 40 MB.
451 4.3.0Falha temporária. Tente de novo.