SMTP 릴레이

SMTP 릴레이를 사용하면 SMTP만 지원하는 소프트웨어(CMS, 인증 제공업체, 프레임워크, 레거시 앱)도 SpacePost를 통해 발송할 수 있습니다. 메시지는 API와 같은 파이프라인을 거칩니다. 도메인 확인, 발송 제외 목록, 할당량, 추적, 웹훅이 모두 적용됩니다.

설정	값
호스트	`smtp.spacepost.dev`
포트	`25976`
보안	STARTTLS, 인증 전에 필수
사용자 이름	`spacepost`(마이그레이션을 위해 별칭 `resend`도 허용)
비밀번호	API 키(`sp_live_...`)

TLS 없이 연결한 뒤 로그인하기 전에 STARTTLS로 업그레이드하세요. 인증서는 smtp.spacepost.dev에 대해 유효합니다. 암시적 TLS(포트 465)는 아직 제공되지 않으므로, 대부분의 클라이언트에서 “SSL”이 아니라 “STARTTLS” 또는 “TLS”를 선택하세요.

From 주소는 확인된 도메인에 속해야 합니다. sending_access 키로 충분하며, 도메인으로 제한된 키는 해당 도메인에서만 발송할 수 있습니다.

제어 헤더

SMTP에 해당 필드가 없는 기능을 사용하려면 메시지에 이 헤더를 추가하세요. 헤더는 SpacePost가 처리하며 수신자에게는 전달되지 않습니다.

헤더	예시	효과
`X-SpacePost-Tags`	`category=welcome, user_id=u_1042`	태그를 추가합니다. 쉼표로 구분한 `name=value` 쌍이며, 문자 규칙은 API와 같습니다.
`X-SpacePost-Scheduled-At`	`2026-11-01T09:00:00Z` 또는 `in 1 hour`	이메일을 예약 발송합니다(최대 30일).

그 밖의 X-* 헤더, List-Unsubscribe, List-Unsubscribe-Post, In-Reply-To, References는 사용자 지정 헤더로 그대로 전달됩니다.

예제

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."

메시지가 매핑되는 방식

To, Cc, Reply-To는 헤더에서 가져옵니다. To나 Cc에 없는 봉투 수신자(RCPT TO)는 Bcc가 됩니다.
HTML 및 텍스트 부분은 그대로 유지됩니다. 인라인 이미지(Content-ID)를 포함한 첨부 파일을 지원합니다.
제목이 없는 메시지의 제목은 (no subject)가 됩니다.
API와 마찬가지로 수신자마다 할당량에서 차감됩니다.

한도와 오류 코드

한도	값
메시지 크기	40 MB, 응답 `552`
인증 실패	IP당 10분 동안 10번 실패하면 차단

SMTP 응답은 API 오류와 다음과 같이 대응합니다.

상황	응답
일일 또는 월 할당량 초과	`452`(일시적: 소프트웨어가 나중에 재시도함)
요청 제한	`421`
`From` 도메인이 확인되지 않음	`553`
제한된 키, 일시 중지된 팀, 검증 오류, 콘텐츠 차단	`550`
서비스 측 일시적 문제	`451`

프레임워크 가이드