Relay SMTP

O relay SMTP permite que softwares que só falam SMTP (CMSs, provedores de autenticação, frameworks, apps legados) enviem pelo SpacePost. As mensagens passam pelo mesmo pipeline da API: verificações de domínio, lista de supressão, cotas, rastreamento e webhooks.

Configuração	Valor
Host	`smtp.spacepost.dev`
Porta	`25976`
Segurança	STARTTLS, obrigatório antes de autenticar
Usuário	`spacepost` (o alias `resend` também é aceito, para migrações)
Senha	Sua chave de API (`sp_live_...`)

Conecte-se sem TLS e faça o upgrade com STARTTLS antes de fazer login; o certificado é válido para smtp.spacepost.dev. O TLS implícito (porta 465) ainda não é oferecido, então, na maioria dos clientes, escolha “STARTTLS” ou “TLS”, não “SSL”.

O endereço From deve pertencer a um domínio verificado. Uma chave sending_access basta; uma chave restrita a um domínio só pode enviar desse domínio.

Cabeçalhos de controle

Adicione estes cabeçalhos à sua mensagem para usar recursos para os quais o SMTP não tem um campo. Eles são consumidos pelo SpacePost e não são entregues ao destinatário.

Cabeçalho	Exemplo	Efeito
`X-SpacePost-Tags`	`category=welcome, user_id=u_1042`	Adiciona tags. Pares `name=value` separados por vírgula; as mesmas regras de caracteres da API.
`X-SpacePost-Scheduled-At`	`2026-11-01T09:00:00Z` ou `in 1 hour`	Agenda o e-mail (até 30 dias).

Os outros cabeçalhos X-*, List-Unsubscribe, List-Unsubscribe-Post, In-Reply-To e References são encaminhados como cabeçalhos personalizados.

Exemplos

import nodemailer from "nodemailer";

const transport = nodemailer.createTransport({
  host: "smtp.spacepost.dev",
  port: 25976,
  secure: false, // STARTTLS: the connection is upgraded to TLS before login
  requireTLS: true,
  auth: { user: "spacepost", pass: process.env.SPACEPOST_API_KEY },
});

await transport.sendMail({
  from: "Acme <hello@acme.com>",
  to: "user@example.com",
  subject: "Hello over SMTP",
  html: "<p>It works.</p>",
  headers: { "X-SpacePost-Tags": "category=welcome", "X-SpacePost-Scheduled-At": "in 10 minutes" },
});

import os, smtplib
from email.message import EmailMessage

msg = EmailMessage()
msg["From"] = "Acme <hello@acme.com>"
msg["To"] = "user@example.com"
msg["Subject"] = "Hello over SMTP"
msg["X-SpacePost-Tags"] = "category=welcome"
msg.set_content("It works.")
msg.add_alternative("<p>It works.</p>", subtype="html")

with smtplib.SMTP("smtp.spacepost.dev", 25976) as s:
    s.starttls()
    s.login("spacepost", os.environ["SPACEPOST_API_KEY"])
    s.send_message(msg)

swaks --server smtp.spacepost.dev --port 25976 --tls \
  --auth-user spacepost --auth-password "$SPACEPOST_API_KEY" \
  --from hello@acme.com --to delivered@test.spacepost.dev \
  --header "Subject: Hello" --header "X-SpacePost-Tags: category=test" --body "It works."

Como as mensagens são mapeadas

To, Cc e Reply-To vêm dos cabeçalhos. Os destinatários do envelope (RCPT TO) que não estão em To nem em Cc viram Bcc.
As partes em HTML e em texto são preservadas. Os anexos, inclusive imagens inline (Content-ID), têm suporte.
Uma mensagem sem assunto recebe o assunto (no subject).
Cada destinatário conta para a sua cota, como na API.

Limites e códigos de erro

Limite	Valor
Tamanho da mensagem	40 MB, resposta `552`
Falhas de autenticação	10 tentativas com falha por IP em 10 minutos, e depois bloqueio

As respostas SMTP correspondem aos erros da API:

Situação	Resposta
Cota diária ou mensal excedida	`452` (temporário: o seu software tentará de novo mais tarde)
Limite de taxa atingido	`421`
Domínio de `From` não verificado	`553`
Chave restrita, equipe pausada, erros de validação, conteúdo bloqueado	`550`
Problema temporário do nosso lado	`451`

Guias por framework