Request a new SMS sender name
Submits the name for admin review and stays pending. Account owners only (team members cannot create via API). Optional webhookUrl and webhookSecret for approve or reject callbacks.
When to use it. When your system needs a new sender name before campaigns.
Code example
Correct: Request a new name
curl --location 'https://raselsms.com/api/v2/sms-senders' \--header 'X-API-Key: YOUR_API_KEY' \--header 'Content-Type: application/json' \--data '{"name":"MyBrand","webhookUrl":"https://your-system.com/webhooks/rasel/sender-status","webhookSecret":"your-long-random-secret"}'Incorrect: Incorrect: duplicate name
curl --location 'https://raselsms.com/api/v2/sms-senders' \--header 'X-API-Key: YOUR_API_KEY' \--header 'Content-Type: application/json' \--data '{"name":"MyBrand"}'The name must be unique on the account.
Response example
201 — Request a new name
{ "success": true, "message": "Sender submitted for review", "data": { "smsSender": { "id": "6800abc123def4567890fedc", "name": "MyBrand", "status": "pending", "isDefault": false, "webhookConfigured": true } }}400 — Incorrect: duplicate name
{ "success": false, "code": "VALIDATION_ERROR", "error": "Sender name already exists"}The name must be unique on the account.
401 — Invalid API key.
{ "success": false, "requestId": "msgreq_1739012345678_abc123", "code": "UNAUTHORIZED", "error": "Missing or invalid API key"}HTTP request
POST /api/v2/sms-senders
Request Headers
| Header | Type | Description |
|---|---|---|
| X-API-Key | string | Your Rasel API key. Send it on every documented request except inbound webhooks. * |
Request body
| Field | Type | Description | Example |
|---|---|---|---|
| name | string | Display name or lowercase template identifier, depending on the endpoint. * | |
| webhookUrl | string | HTTPS URL that receives approve or reject events. | |
| webhookSecret | string | Required with webhookUrl. Rasel sends it as Bearer on callbacks and never returns it. |
Response Fields
| Field | Type | Description | Example |
|---|---|---|---|
| success | boolean | True when the operation succeeded, or when at least one batch recipient succeeded. | |
| data | object | Primary payload for list and snapshot endpoints. | |
| data.smsSender | string | The SMS sender that was created or returned. | |
| message | string | Human-readable result message from create or upload. |
Status Codes
| Status | Description |
|---|---|
| 201 | Created. |
| 400 | Invalid request, validation error, or the resource cannot be used in this state. |
| 401 | Missing or invalid API key. |
| 403 | Phone not verified, missing permission, or the account cannot perform this action. |
| 429 | Rate limit exceeded, or the maximum number of verification attempts was reached. |
Cases to handle
- Webhook callback: Authorization: Bearer <secret> and X-Rasel-Event: sms_sender.approved | sms_sender.rejected.
Try it
Parameters
Display name or lowercase template identifier, depending on the endpoint.
HTTPS URL that receives approve or reject events.
Required with webhookUrl. Rasel sends it as Bearer on callbacks and never returns it.
Request
{}Response
Send a request to see the response.