지식 베이스

REST API

발급하고, 스코프를 지정하고, 철회할 수 있는 키를 갖춘 문서화된 HTTP API입니다.

세부 사항

어디서나 켜져 있습니다. 이 API는 68개 경로에 걸쳐 104개의 문서화된 작업(emails, threads, drafts, labels, contacts, audiences, domains, templates, rules, roles, members, settings, calendar, tracking, webhooks 및 계정)을 제공하며, 키 없이 GET /openapi.json에서 읽을 수 있는 확정된 OpenAPI 3.1 문서가 이를 뒷받침합니다. 접근 권한은 Settings에서 발급하는 워크스페이스 키로 결정됩니다.
예전에 이 기능이 기다리고 있던 내구성 작업은 끝났습니다. 발송은 무언가 전달되기 전에 먼저 행을 기록하며, 공개 id는 msg_ 뒤에 16진수 24자가 붙는 형태입니다. GET /emails/{id}로 이를 조회할 수 있고, 수신자별 이력은 /events로, 열람과 클릭은 /tracking으로 확인합니다. 1~255자의 Idempotency-Key는 그 키와 사용자의 API 키를 함께 묶은 고유 인덱스에 등록되므로, 타임아웃 이후 재시도하면 두 번 보내는 대신 Idempotency-Replayed: true와 함께 첫 번째 결과가 반환됩니다. 키로 인증된 발송은 처리가 끝나면 200으로, 아직 큐에 있거나 예약된 상태라면 202로 응답합니다.
키는 Settings → API keys에서 발급하고, 스코프를 지정하고, 교체하고, 철회합니다. 콘솔이 발급하는 키는 모두 oe_live_ 키입니다. oe_test_ 접두사는 검증기와 발송 경로가 인식하며, 테스트 모드 발송은 전송 계층에 전혀 닿지 않고도 기록되어 발송된 것으로 응답됩니다. 다만 아직은 그런 키를 발급할 방법이 없습니다. 아무 동작도 하지 않는 전송 계층이 Durable Object 위에 자리 잡기 전에 이 옵션을 제공하면 실제로 메일을 배달하는 테스트 키를 쥐여 주는 셈이 되기 때문입니다. 키에는 최대 25개의 전체 도메인과 50개의 개별 주소로 이뤄진 발송 스코프가 담기며, 전체 도메인은 나중에 추가되는 주소까지 포함합니다. 여기에 1일에서 3650일 사이의 만료를 선택적으로 지정할 수 있고, 역할도 선택적으로 붙일 수 있습니다. 역할은 두 번째 권한 부여가 아니라 상한입니다. GET /ping은 키에 부여된 스코프와 역할이 남겨 준 스코프를 모두 반환하므로, 키가 분명히 가지고 있는 스코프에서 403이 나더라도 원인을 눈으로 확인할 수 있습니다. 철회는 삭제가 아니라 갱신이므로, 이후의 호출은 단순히 인증에 실패하는 대신 revoked_api_key를 받습니다. 교체는 비밀 값만 빼고 키의 모든 것을 유지합니다. id, 스코프, 발송 스코프, 요청 기록이 그대로 이어지고, 새 비밀 값이 발급되는 순간 이전 값은 사라지며, keys:write를 가진 키는 API를 통해 스스로를 교체할 수 있습니다. 목록 조회, 교체, 철회, 활성화라는 동일한 작업이 키를 관리할 수 있는 역할을 가진 사람 누구에게나 MCP 서버에도 제공됩니다.
정말로 없는 것은 이렇습니다. 이 API에는 자체 업로드 엔드포인트가 없습니다. 인라인 첨부는 총 5 MB 한도 안에서 base64로 전송되며, 더 큰 파일은 워크스페이스에 이미 있는 파일을 id로 지정해 보내고 다운로드 링크 형태로 전달됩니다. 반송은 발송 로그가 아니라 메일함에서 처리됩니다. 배달 보고서를 파싱해 Message-ID로 원본과 연결하고, 스레드에 라벨을 붙이고, email.bounced 웹훅으로 내보내지만, 발송 행에는 아무것도 기록되지 않습니다. 발송 행의 상태에는 반송 상태가 없어서 GET /emails로 보면 반송된 메시지도 여전히 발송된 것으로 읽힙니다. 앱의 작성 창에서 보낸 메일도 GET /emails에 나타나지 않습니다. 작성 창은 동일한 발송 경로를 거쳐 기록하지 않기 때문입니다.