Documentation version: Latest (v1)
API endpoint
Queue an email
Queues transactional or template mail with optional sender routing and priority.
POST/api/v1/emails
Auth: Bearer API key with mail_api scope
Required headers
| Header | Required | Value | Description |
|---|---|---|---|
| Authorization | Yes | Bearer <token> | API key, server OTP key, or public OTP token depending on endpoint. |
| Content-Type | Yes | application/json | All POST requests expect JSON payloads. |
Request body
| Field | Type | Required | Description |
|---|---|---|---|
| to | string | string[] | Yes | Single recipient or list (max 100). |
| subject | string | Yes | Email subject line (max 998 chars). |
| html | string | No | HTML body. |
| text | string | No | Text fallback body. |
| imageUrl | string | No | Optional https image URL included in body. |
| templateId | string | No | Use saved template instead of inline html/text. |
| vars | object | No | Template variables for {{key}} placeholders. |
| priority | 'URGENT' | 'NORMAL' | No | URGENT can bypass freeze mode. |
| senderEmailId | string | No | Verified sender identity id. |
Code examples (all supported languages)
Snippets use placeholder tokens. Replace them with real credentials from your dashboard.
curl -X POST "https://risumail.risu.in/api/v1/emails" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"to":["user@example.com"],"subject":"Welcome to Risu Mail","html":"<h1>Hello</h1><p>Your onboarding flow is active.</p>"}'Response schema
Canonical schema inferred from the documented success payload. Copy this block when generating typed clients.
{
"type": "object",
"required": [
"success",
"data"
],
"properties": {
"success": {
"type": "boolean"
},
"data": {
"type": "object",
"required": [
"id",
"status"
],
"properties": {
"id": {
"type": "string"
},
"status": {
"type": "string"
}
}
}
}
}Success response example
{
"success": true,
"data": {
"id": "mail_01J...",
"status": "QUEUED"
}
}Common error cases
| Status | Code | When |
|---|---|---|
| 400 | INVALID_INPUT | Missing to/subject or body/template. |
| 403 | SENDER_NOT_VERIFIED | senderEmailId does not belong to caller. |
| 429 | RATE_LIMITED | IP or API-key window exceeded. |
| 503 | SMTP_NOT_CONFIGURED | Outbound SMTP is unavailable. |
Implementation notes
- At least one of html/text/imageUrl or templateId must be provided.
- If SMTP pool daily warmup is exhausted, endpoint returns a limit message with reset timing.