認証
全リクエストに 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 を返し、その後の状態はイベントと Webhook で還流。
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 — 1 リクエスト最大 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", ... }
Webhook イベント
コンソールでエンドポイントを登録 — イベントは 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