List queued/sent emails

Returns paginated send log for the authenticated user.

GET/api/v1/emails?page=1&limit=20

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.

Query parameters

Field	Type	Required	Description
page	number	No	Page number (default 1).
limit	number	No	Items per page (1-100).

Code examples (all supported languages)

Snippets use placeholder tokens. Replace them with real credentials from your dashboard.

curl -X GET "https://risumail.risu.in/api/v1/emails?page=1&limit=20" \
  -H "Authorization: Bearer YOUR_API_KEY"

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": [
        "emails",
        "total",
        "page",
        "totalPages"
      ],
      "properties": {
        "emails": {
          "type": "array",
          "items": {
            "type": "object",
            "required": [
              "id",
              "subject",
              "toAddresses",
              "status",
              "createdAt"
            ],
            "properties": {
              "id": {
                "type": "string"
              },
              "subject": {
                "type": "string"
              },
              "toAddresses": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "status": {
                "type": "string"
              },
              "createdAt": {
                "type": "string"
              }
            }
          }
        },
        "total": {
          "type": "number"
        },
        "page": {
          "type": "number"
        },
        "totalPages": {
          "type": "number"
        }
      }
    }
  }
}

Success response example

{
  "success": true,
  "data": {
    "emails": [
      {
        "id": "mail_01J...",
        "subject": "Welcome",
        "toAddresses": [
          "user@example.com"
        ],
        "status": "SENT",
        "createdAt": "2026-04-19T08:13:11.022Z"
      }
    ],
    "total": 1,
    "page": 1,
    "totalPages": 1
  }
}

Common error cases

Status	Code	When
401	UNAUTHORIZED	Missing or invalid API key.
403	SCOPE_REQUIRED	Key does not include mail_api scope.
429	RATE_LIMITED	Read quota exceeded.

Implementation notes

Use this endpoint for delivery status polling and dashboard integrations.

Back to API reference index Error handling playbook