목록 조회와 단건 조회
메시지를 찾고, 하나가 어떻게 되었는지 확인합니다.
이 페이지의 3개 호출을 본인 키로 워크스페이스에 실제로 실행합니다.
목록 조회
GET /emails, 최신순입니다. status(쉼표로 구분)와 from으로 필터링합니다. 페이지네이션은 오프셋이 아니라 키셋입니다. 받은 nextCursor를 그대로 전달하세요. 오프셋 페이징은 페이지를 넘기는 동안 새 메시지가 도착하면 행을 조용히 건너뜁니다.
{ "object": "list", "data": [ … ], "hasMore": true, "nextCursor": "msg_01j8…" }추적된 행에는 간결한 tracking 객체도 함께 담깁니다. opens, clicks, opened, clicked, openCount, clickCount, firstOpenAt입니다. 추적되지 않은 행에는 tracking 키 자체가 없습니다. 픽셀을 담은 적 없는 메시지에 openCount: 0을 붙이면 "아무도 열지 않았다"로 읽히는데, 그건 우리가 할 수 있는 주장이 아니기 때문입니다.
단건 조회
GET /emails/{id}는 수신자별 전달 상태와 함께 메시지를 반환하며, 목록의 요약이 아니라 전체 추적 리포트를 담습니다. 단건 조회라면 수신자별 내역과 링크까지 감당할 수 있기 때문입니다. 존재하지 않는 id는 404이며, 꾸며 낸 성공 응답은 절대 없습니다.
| 수신자 상태 | 의미 |
|---|---|
| pending | 아직 전송되지 않았습니다. |
| delivered | 이 주소에 대해 전송 계층에 넘겨졌습니다. |
| failed | 전송 계층이 거부했습니다. |
| uncertain | 전송 계층이 도중에 실패해 어떤 수신자에게 도달했는지 말할 수 없습니다. 어느 쪽으로도 추측하지 않고 있는 그대로 표시합니다. |
이벤트
GET /emails/{id}/events는 오래된 순으로 이력을 반환합니다. email.accepted, email.queued, email.scheduled, email.sent, email.failed, email.cancelled, email.rescheduled가 있고, 추적된 메시지라면 발생하는 대로 email.opened, email.clicked, email.downloaded도 담깁니다. 폴링하지 않고 통지받으려면 웹훅을 등록하세요.