Email Shared Service API

Send transactional emails with HTML or plain-text content and message status tracking. Each request must include non-empty html or text content. Teams provide the content in each request; APICenter does not store email templates.

For a Node.js backend, the typed client is api.email.send(...) in the APICenter SDK. The REST reference below documents the same API for other runtimes.

Service Specifications

• Base Route: /api/v1/shared/email
• Required Header: Authorization: Bearer <SERVICE_ACCESS_TOKEN>
• Required Header: Idempotency-Key: <16–255 characters>

1. Send Transactional Email

• Endpoint: POST /api/v1/shared/email/send

Request Body (EmailSendRequest)

The optional from address must match the sender approved for the project and environment. If omitted, APICenter uses the approved project sender or its default sender.

{
  "to": "customer@example.com",
  "subject": "Payment Receipt for ORDER-991204",
  "html": "<h1>Payment Successful</h1><p>Thank you for your purchase of PHP 499.00.</p>",
  "tags": {
    "category": "receipt"
  }
}

Response (EmailSendResponse) — 201 Created

{
  "success": true,
  "data": {
    "messageId": "msg_77182a994ff34e028b1239910a",
    "status": "sent",
    "recipientCount": 1,
    "sentAt": "2026-07-31T23:20:00.000Z",
    "provider": "resend",
    "recipient": ["customer@example.com"]
  }
}

Retries with the same key and request body replay the original status and response for seven days. Reusing a key with a different body returns 409 IDEMPOTENCY_KEY_PAYLOAD_MISMATCH. If delivery has an uncertain outcome, APICenter blocks the key for reconciliation instead of sending again.

2. Get Message Status

• Endpoint: GET /api/v1/shared/email/status/:messageId

Response — 200 OK

{
  "success": true,
  "data": {
    "messageId": "msg_77182a994ff34e028b1239910a",
    "status": "sent",
    "recipient": ["customer@example.com"],
    "createdAt": "2026-07-31T23:20:00.000Z"
  }
}

Requests without non-empty html or text content return 400 EMAIL_CONTENT_REQUIRED. Requests containing the obsolete templateId or templateVariables fields also return 400; send the rendered email content directly in html or text instead.