SMTP 게이트웨이

SMTP 게이트웨이는 표준 메일 제출을 수락하고 각 메시지를 트랜잭션 이메일로 Messaging API v2 Notify로 전달합니다. 기존 메일 도구(MTA, 프레임워크 메일러, SDK)를 API에 대한 JSON 요청보다 더 쉽게 연결할 수 있을 때 사용하십시오.

작동 방식

   any SMTP client          smtp gateway              Messaging API v2
   ──────────────── ──────> ──────────────── ──────> ─────────────────
       submission            STARTTLS                gRPC Notify
       AUTH PLAIN            + AUTH PLAIN            Authorization: Token

클라이언트는 포트 587에서 smtp.pushwoosh.com에 연결하고, STARTTLS를 사용하여 연결을 TLS로 업그레이드한 다음, AUTH PLAIN으로 인증합니다.
게이트웨이는 MIME 메시지를 파싱하고 platforms: ["EMAIL"] 및 message_type: TRANSACTIONAL을 사용하여 Notify 요청을 빌드합니다.
AUTH PLAIN의 API 토큰은 Authorization 헤더로 Messaging API에 전달됩니다. 토큰 유효성 검사, 애플리케이션 매칭, 발신자 ID 및 반송 처리는 모두 API 측에서 이루어집니다.

엔드포인트

설정	값
호스트	`smtp.pushwoosh.com`
포트	`587` (SMTP 제출)
TLS	`STARTTLS` — `AUTH` 전에 필수
인증	`AUTH PLAIN`

인증

AUTH PLAIN은 두 개의 Pushwoosh 자격 증명을 사용합니다.

AUTH 필드	Pushwoosh 값
`username`	애플리케이션 코드, 예: `XXXXX-XXXXX`
`password`	서버 API 토큰

AUTH는 TLS 외부에서 거부됩니다. 토큰은 메시지에 절대 나타나지 않으며, 업스트림 Notify 호출을 승인하는 데만 사용됩니다.

메시지가 Notify에 매핑되는 방식

MIME 또는 SMTP 필드	Notify 필드
`RCPT TO`	`target.users.list` — Pushwoosh는 이러한 주소를 구독자로 확인합니다
AUTH `username`	`application`
`Subject:` 헤더	`email_payload.subject["default"]` (RFC 2047 디코딩됨)
`From:` 헤더	`email_payload.from` — `name` 및 `email`
HTML 부분	`email_payload.body` (두 부분이 모두 있을 때 선호됨)
일반 텍스트 부분	`email_payload.body` (HTML이 없을 때 사용됨)
`MAIL FROM`	무시됨 — Pushwoosh는 자체 발신자 ID를 대체하고 반송을 직접 처리합니다

모든 메시지는 schedule.send_date: now로 전송됩니다.

제한

제한	값
최대 메시지 크기	25 MiB
봉투당 최대 수신자 (`RCPT TO`)	50

오류 매핑

Messaging API에서 반환된 gRPC 상태 코드는 표준 SMTP 응답 코드로 변환되어 모든 SMTP 클라이언트가 의미 있는 오류를 표시하도록 합니다.

업스트림 gRPC 상태	SMTP 응답	의미
`Unauthenticated`	`535 5.7.8`	잘못된 애플리케이션 코드 또는 API 토큰입니다.
`PermissionDenied`	`550 5.7.1`	토큰에 이 애플리케이션에 대한 권한이 없습니다.
`InvalidArgument` / `FailedPrecondition` / `OutOfRange`	`550 5.6.0`	잘못된 MIME 콘텐츠입니다 (예: 제목 또는 본문 누락).
`NotFound`	`550 5.1.1`	애플리케이션 또는 수신자를 찾을 수 없습니다.
`ResourceExhausted`	`452 4.5.3`	속도 제한에 도달했습니다 — 나중에 다시 시도하십시오.
`DeadlineExceeded` / `Unavailable`	`451 4.4.1`	일시적인 업스트림 오류입니다 — 나중에 다시 시도하십시오.
기타 모든 실패	`451 4.5.0`	일시적인 내부 오류입니다 — 나중에 다시 시도하십시오.

4xx 범위의 코드는 일시적이므로 클라이언트가 다시 시도해야 합니다. 5xx 범위의 코드는 영구적이므로 클라이언트 측 수정이 필요합니다.

예시: swaks로 보내기

swaks --server smtp.pushwoosh.com:587 \
      --auth-user "XXXXX-XXXXX" \
      --auth-password "YOUR_API_TOKEN" \
      --tls \
      --from from@example.com \
      --to user@example.com \
      --header "Subject: Hello from SMTP gateway" \
      --body "Plain-text body"

MIME 본문의 From: 헤더가 Pushwoosh에 도달하는 것이며, --from 봉투(MAIL FROM)는 폐기됩니다.

참고

게이트웨이는 상태 비저장(stateless)이며 메시지를 저장하지 않습니다. 일단 전달되면 배달은 Messaging API가 담당합니다.
반송, 불만 사항 및 구독 취소 링크는 다른 모든 트랜잭션 이메일과 마찬가지로 Pushwoosh에서 처리합니다.
캠페인 발송(세그먼트, 스케줄링, A/B)의 경우 Notify를 직접 사용하십시오. SMTP 게이트웨이는 제출 전용입니다.