Email API
표준 HTTP로 연동하고 요청 필드, 접수 결과 및 메시지 상태를 확인하세요.
1. 인증 및 주소
발송 및 조회에는 Authorization: Bearer <API Key>를 사용합니다. API origin과 프록시 접두사를 확인하세요. 페이지 언어 접두사를 API 경로에 붙이지 마세요. 키는 서버에서만 보관합니다. 예제는 표준 HTTP이며 SMTPDog SDK가 아닙니다.
2. 이메일 한 건 발송
POST /v1/mail/send는 JSON을 받습니다. from과 to는 각각 단일 주소 문자열이며 배열이 아닙니다. 템플릿 없이 보내려면 비어 있지 않은 subject와 text 또는 html이 필요합니다. cc, bcc, attachments, 일괄 및 예약 발송은 지원하지 않습니다.
| 필드 / 설정 | 타입 / 상태 | 설명 |
|---|---|---|
| from | string | 발신자 1명, Name <addr> 형식 가능, 인증 도메인, 이름 최대 100자 |
| to | string | 수신자 1명, 배열 불가 |
| subject | string | 템플릿 없을 때 필수, CR/LF 불가 |
| html / text | string | 템플릿 없을 때 하나 이상 비어 있지 않은 본문. html과 text를 함께 보내는 것을 권장하며, 일반 텍스트 본문이 있으면 스팸으로 분류될 가능성이 낮아집니다 |
| reply_to | string | 선택, 회신 주소 1개 |
| headers | map<string,string> | 선택, List-Unsubscribe, List-Unsubscribe-Post, Auto-Submitted만 허용 |
| template_id | uint64 | 선택, 계정 소유 템플릿 ID |
| variables | map<string,string> | 선택, 문자열 값 변수 |
curl -X POST "${SMTPDOG_API_ORIGIN}/v1/mail/send" \
-H "Authorization: Bearer ${SMTPDOG_API_KEY}" \
-H "Content-Type: application/json" \
--data '{
"from": "sender@example.com",
"to": "recipient@example.com",
"subject": "Welcome to your product",
"text": "Your message goes here."
}'3. 접수 및 상태 조회
202는 message_id와 queued를 반환합니다. GET /v1/mail/{message_id}로 계정 소유 메시지 상태를 조회합니다. created_at은 항상 있고 delivered_at과 smtp_response는 생략될 수 있습니다. sent는 노드 접수를 의미할 수 있으며 받은편지함 도착이나 열람 확인이 아닙니다. 도메인 제한 키도 조회는 계정 소유 기준입니다.
| 필드 / 설정 | 타입 / 상태 | 설명 |
|---|---|---|
| queued | string | 대기열 접수 |
| sending | string | 발송 제출 중 |
| sent | string | 노드 접수 등, 받은편지함 보장 없음 |
| deferred | string | 임시 지연, 후속 상태 확인 |
| bounced | string | 반송 |
| failed | string | 발송 실패 |
{
"message_id": "00000000-0000-4000-8000-000000000000",
"status": "queued"
}4. 기존 템플릿 사용
template_id는 본인 계정의 템플릿이어야 합니다. 템플릿이 인라인 subject, html, text를 전부 대체한 뒤 결과를 검증합니다. variables 값은 문자열만 가능하며 {{name}} 단순 치환입니다. 누락 값은 자리표시자로 남고 HTML은 이스케이프됩니다. 반복·조건식은 지원하지 않습니다. 실제 생성한 ID를 사용하세요.
{
"from": "sender@example.com",
"to": "recipient@example.com",
"template_id": 123,
"variables": {
"name": "Example recipient"
}
}5. 오류 및 재시도
일반 오류는 code와 error를 포함합니다. code로 판단하세요. error는 현재 5개 언어 프로토콜이 아닙니다. 권한·설정 오류를 반복 제출하지 마세요. 시간 초과 요청도 접수됐을 수 있습니다. 멱등 키나 재발송 API가 없으므로 중복 발송·차감될 수 있습니다. 실패 요청의 한도 반환도 보장되지 않습니다.
| 필드 / 설정 | 타입 / 상태 | 설명 |
|---|---|---|
| 400 invalid_request | HTTP | 타입·제목·본문 확인 |
| 401 api_key_invalid | HTTP | 키·계정 상태 확인 |
| 403 domain_unverified / api_key_domain_forbidden / content_blocked | HTTP | 인증·범위·콘텐츠 확인 |
| 404 template_not_found / message_not_found | HTTP | ID 및 계정 소유 확인 |
| 429 quota_exceeded | HTTP | 총·일·시간 한도 확인, 무조건 재시도 금지 |
| 500 internal_error | HTTP | 오류 맥락 보관 후 지원 문의, 부분 처리 가능 |