인증
모든 요청에 Authorization 헤더를 담습니다. 키는 콘솔에서 생성 — 평문은 한 번만 표시.
curl https://api.nexorelay.com/v1/emails \
-H "Authorization: Bearer nxr_live_xxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-d '{ ... }'
콘솔에서 API 키 받기 →메일 전송
POST /v1/emails — 발신 도메인과 파라미터를 동기 검증. 큐 적재 시 202와 메일 ID 반환, 이후 상태는 이벤트와 웹훅으로 전달.
POST https://api.nexorelay.com/v1/emails
{
"from": "Acme <
[email protected]>",
"to": ["
[email protected]"],
"subject": "Hello",
"html": "<strong>Hi</strong>",
"tags": { "order_id": "123" }
}
응답 202
{ "id": "email_abc123" }
템플릿 전송
template_id와 variables 전달(subject/html/text와 상호 배타). 변수는 Handlebars 문법.
배치 전송
POST /v1/emails/batch — 요청당 최대 100통, 각각 다른 내용 가능.
POST https://api.nexorelay.com/v1/emails/batch
{ "emails": [ { "from": "...", "to": ["..."], "subject": "..." } ] }
→ 202 { "ids": ["email_1", "email_2", ...] }
메일 조회
GET https://api.nexorelay.com/v1/emails/email_abc123
→ 200 { "id": "email_abc123", "status": "DELIVERED", ... }
웹훅 이벤트
콘솔에서 엔드포인트 등록 — 이벤트는 HMAC 서명으로 도착: email.sent / delivered / bounced / complained / opened / clicked.
POST https://api.acme.com/hooks/nexorelay
X-Nexorelay-Signature: sha256=...
{ "type": "email.delivered", "data": { "id": "email_abc123" } }
오류 형식
통일된 오류 봉투 — type은 범주, code는 기계 판독 가능한 원인.
{
"error": {
"type": "invalid_request_error",
"code": "domain_not_verified",
"message": "The sending domain \"mail.example.com\" is not verified."
}
}
멱등성与 제한
Idempotency-Key 헤더 — 24h 내 동일 key+body는 첫 응답 반환, 다른 body는 409. 기본 제한: 키당 10 req/s.
Idempotency-Key: order-8742