API 소개

SpacePost API는 Resend API와 호환되는 JSON REST API입니다. 전체 엔드포인트 목록은 OpenAPI 명세에서 생성된 API 레퍼런스에 있습니다.

기본 URL

https://api.spacepost.dev

경로는 루트에 있습니다(/emails, /domains, …). /v1 접두사도 허용되며 https://api.spacepost.dev/v1/emails는 같은 엔드포인트입니다. 클라이언트가 선호하는 쪽을 사용하세요.

인증

모든 요청에 API 키를 bearer 토큰으로 보내세요.

curl https://api.spacepost.dev/emails -H "Authorization: Bearer sp_live_YOUR_API_KEY"

키는 sp_live_로 시작합니다. full_access 키는 모든 엔드포인트를 사용할 수 있고, sending_access 키는 이메일 발송만 가능하며 선택적으로 도메인 하나에서만 보낼 수 있습니다. 보안 및 API 키를 참고하세요.

문제	응답
`Authorization` 헤더 없음	`401 missing_api_key`
알 수 없거나, 폐기되었거나, 형식이 잘못된 키(Resend `re_` 키 포함)	`403 invalid_api_key`
발송용이 아닌 엔드포인트에 `sending_access` 키 사용	`401 restricted_api_key`

요청

Content-Type: application/json으로 JSON을 보내세요. 잘못된 JSON은 422 validation_error를 반환합니다.
필드는 snake_case입니다(reply_to, scheduled_at). 편의를 위해 발송할 때 replyTo와 scheduledAt도 허용됩니다.
ID는 UUIDv7 문자열이며 생성 시각순으로 정렬됩니다. 페이지네이션이 이 방식으로 동작합니다.
타임스탬프는 UTC 기준 ISO 8601입니다(2026-10-23T14:02:09.512Z).
요청의 알 수 없는 필드는 무시됩니다.

응답

성공 응답은 상태 200의 JSON입니다. 리소스에는 유형을 나타내는 object 필드가 있습니다("email", "domain", …). 목록은 { "object": "list", "has_more": false, "data": [] } 형태입니다.

오류는 항상 같은 형식입니다.

{ "statusCode": 422, "name": "validation_error", "message": "`to`: Invalid email address" }

모든 name은 오류를 참고하세요.

멱등성

POST /emails와 POST /emails/batch는 Idempotency-Key 헤더(1자 이상 256자 이하, 24시간 동안 기억)를 받습니다. 같은 키와 본문이면 다시 발송하지 않고 첫 번째 응답을 반환합니다. 멱등성 키를 참고하세요.

요청 한도

팀당 초당 10건(Scale은 25건)이며 ratelimit-* 헤더로 반환됩니다. 요청 한도를 참고하세요.

버전 관리

API는 Resend의 현재 형식을 따르며 날짜 기반 버전을 사용하지 않습니다. 기존 엔드포인트에는 하위 호환되는 변경(새 선택 필드, 응답의 새 필드, 새 이벤트 유형과 오류 이름)만 적용하므로, 알 수 없는 필드는 무시하고 알 수 없는 오류 이름도 처리하도록 클라이언트를 작성하세요. 호환성을 깨는 변경은 새 경로 접두사로 제공하며 변경 내역에 사전에 공지합니다.

CORS

API 탐색기에서 호출할 수 있도록 허용적인 CORS 헤더를 보내지만, 실제 키로 브라우저에서 호출하지 마세요. 키는 서버에 있어야 합니다.

SDK와 도구