지식 베이스

이메일 API

호출 한 번에 한 통이든 백 통이든, 지금이든 나중이든 보내고, 재시도해도 두 번 보내지 않습니다.

세부 사항

POST /emails는 메시지 한 통을, POST /emails/batch는 서로 독립된 최대 100통을 보냅니다. 배치는 전부 아니면 전무가 아닙니다. 7번째 항목의 주소가 잘못되면 7번째만 실패하고 나머지는 나가며, 응답은 항목마다 따로 알려 줍니다.
본문은 정확히 한 곳에서 옵니다. html과 text 중 하나 또는 둘, ID나 슬러그로 지정한 저장된 템플릿(다른 사람이 문구를 관리한다면 버전을 고정), 또는 기존 임시 보관 메일입니다. 태그는 최대 10개까지 함께 가며 읽을 때마다 돌아옵니다.
scheduledAt은 ISO 8601 시각이나 PT1H 같은 기간으로 메시지를 최대 365일 붙잡아 둡니다. cancellableForSeconds는 즉시 발송에 최대 900초의 취소 여유를 줍니다. 둘 다 나가기 전까지 취소할 수 있고, 예약 발송은 다시 예약할 수 있습니다.
모든 발송에는 무엇이든 나가기 전에 확보되는 Idempotency-Key가 붙습니다. 그래서 시간 초과 후 재시도하면 첫 결과가 Idempotency-Replayed: true와 함께 돌아옵니다. 같은 키에 다른 본문을 보내면 idempotency_key_reuse로 거부됩니다.
모든 발송은 접수된 순간부터 msg_ ID를 가집니다. GET /emails/{id}로 읽고, /events로 수신자별 기록을, /tracking으로 열람과 클릭을 봅니다.
translate를 추가하면 메시지가 수신자의 언어로 전달됩니다. 번역은 요청을 받을 때 이루어지므로 예약 발송에는 승인한 문구가 그대로 담기고, 번역을 만들 수 없으면 원문으로 돌아가는 대신 발송을 거부합니다.
첨부 파일: 최대 20개, 본문에 넣는 파일은 합계 5MB까지. 더 큰 파일은 워크스페이스 파일의 ID를 지정해 보내며 다운로드 링크로 전달됩니다.
빠진 것: 아직 테스트 모드가 없어서 모든 키가 실제로 전달하며, 발송 기록에는 반송 상태가 없습니다. 반송은 스레드에 라벨이 붙고 email.bounced 웹훅으로 알려지지만, GET /emails에는 여전히 sent로 나옵니다.
발송 차단 목록, 즉 설정의 차단된 주소는 API에도 있습니다. GET /suppressions는 검색과 사유 필터로 목록을 읽고, POST /suppressions는 주소를 직접 차단하며, DELETE /suppressions/{id}는 주소를 다시 허용합니다. 단 하드 바운스는 그대로 남습니다. SDK와 MCP 서버도 같은 일을 하고, 변경할 때마다 suppression.added 또는 suppression.removed 웹훅이 발생합니다.