Bulk job rows
A page of 50 rows for the owning account. cursor is the zero-based row index. nextCursor is null on the last page. Message text and template variables are included. File bytes are not. An unknown status returns an empty page.
When to use it. Show recipient, channel, sender, template, text, and error code row by row.
Code example
Correct: Correct: failed rows
curl --location 'https://raselsms.com/api/v2/messages/bulk/64b0c0ff0000000000000001/items?status=failed&cursor=0' \--header 'X-API-Key: YOUR_API_KEY'Response example
200 — Correct: failed rows
{ "success": true, "items": [ { "index": 0, "status": "failed", "to": "+963912345678", "channel": "local_sms", "senderId": "", "templateName": "", "text": "Example notice from Rasel.", "variables": null, "errorCode": "SEND_FAILED", "errorMessage": "Send failed", "requestId": null } ], "nextCursor": null}200 — A page of rows. received is stored and not checked. pending is ready. sending is claimed. sent is accepted. failed is that row only. cancelled was not sent.
{ "success": true, "items": [], "nextCursor": null}404 — No job with this id belongs to this account. Code JOB_NOT_FOUND.
{ "success": false, "code": "JOB_NOT_FOUND", "error": "Job was not found"}401 — Missing or invalid API key.
{ "success": false, "requestId": "msgreq_1739012345678_abc123", "code": "UNAUTHORIZED", "error": "Missing or invalid API key"}403 — Phone is not verified or messages:read is missing. Code FORBIDDEN.
{ "success": false, "code": "FORBIDDEN", "error": "Phone not verified or missing permission"}429 — Rate limit exceeded. Honor Retry-After when present.
{ "success": false, "requestId": "msgreq_1739012345678_abc123", "code": "RATE_LIMITED", "error": "Rate limit exceeded", "retryAfterSeconds": 30}HTTP request
GET /api/v2/messages/bulk/{jobId}/items
Request Headers
| Header | Type | Description |
|---|---|---|
| X-API-Key | string | Your Rasel API key. Send it on every documented request except inbound webhooks. * |
Path parameters
| Field | Type | Description |
|---|---|---|
| jobId | string | Job id from the create response. The job is visible only to that key's account. * |
Query parameters
| Field | Type | Description |
|---|---|---|
| status | received | pending | sending | sent | failed | cancelled | Delivery or record status. On send: sent, queued, or scheduled. On other resources it is the row status filter or value. |
| cursor | integer | Opaque pagination cursor from the previous response. |
Response Fields
| Field | Type | Description | Example |
|---|---|---|---|
| success | enum | True when the operation succeeded, or when at least one batch recipient succeeded. * | |
| items | json | A page of rows. Each item is one recipient with its state and, on the items route, its text. * | |
| nextCursor | integer | Cursor for the next page. null means this is the last page. Send it back unchanged. * |
Status Codes
| Status | Description |
|---|---|
| 200 | Success. |
| 401 | Missing or invalid API key. |
| 403 | Phone not verified, missing permission, or the account cannot perform this action. |
| 404 | Resource not found for this API key owner. |
| 429 | Rate limit exceeded, or the maximum number of verification attempts was reached. |
Cases to handle
- Message text is shown to the owning account through this route. Do not log the text when it contains a secret code.
Try it
Parameters
Job id from the create response. The job is visible only to that key's account.
Delivery or record status. On send: sent, queued, or scheduled. On other resources it is the row status filter or value.
Opaque pagination cursor from the previous response.
Request
GET /api/v2/messages/bulk//items?status=receivedResponse
Send a request to see the response.