# SMTP 게이트웨이

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

<Aside type="note">
게이트웨이는 트랜잭션 전용입니다. 오디언스 세그먼트, 스케줄링 또는 A/B 캠페인의 경우 [`Notify`](/ko/developer/api-reference/messaging-api-v2/notify/)를 직접 호출하십시오.
</Aside>

## 작동 방식

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

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

## 엔드포인트

| 설정 <div style="width:140px"></div> | 값 <div style="width:340px"></div> |
|---------|-------|
| 호스트    | `smtp.pushwoosh.com` |
| 포트    | `587` (SMTP 제출) |
| TLS     | `STARTTLS` — `AUTH` 전에 필수 |
| 인증    | `AUTH PLAIN` |

## 인증

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

| AUTH 필드 <div style="width:120px"></div> | Pushwoosh 값 |
|------------|-----------------|
| `username` | [애플리케이션 코드](/ko/developer/api-reference/api-identifiers/#application-code), 예: `XXXXX-XXXXX` |
| `password` | [서버 API 토큰](/ko/developer/api-reference/api-access-token/#server-api-token) |

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

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

| MIME 또는 SMTP 필드 <div style="width:200px"></div> | 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`로 전송됩니다.

## 제한

| 제한 <div style="width:280px"></div> | 값 |
|-------|-------|
| 최대 메시지 크기       | 25 MiB |
| 봉투당 최대 수신자 (`RCPT TO`) | 50 |

## 오류 매핑

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

| 업스트림 gRPC 상태 <div style="width:280px"></div> | SMTP 응답 <div style="width:120px"></div> | 의미 |
|----------------------|------------|---------|
| `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로 보내기

```bash
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`](/ko/developer/api-reference/messaging-api-v2/notify/)를 직접 사용하십시오. SMTP 게이트웨이는 제출 전용입니다.

## 관련 항목

<CardGrid>
  <LinkCard title="Messaging API v2 개요" href="/developer/api-reference/messaging-api-v2/" />
  <LinkCard title="Notify" href="/developer/api-reference/messaging-api-v2/notify/" />
  <LinkCard title="이메일 페이로드 참조" href="/developer/api-reference/messaging-api-v2/email-payload-reference/" />
  <LinkCard title="마케팅 vs 트랜잭션" href="/product/messaging-channels/marketing-vs-transactional/" />
</CardGrid>