Senders: Routes
Run Commands
The single entry point for senders. Send 1 to 20 commands in one request and get one result per command.
https://g.sendcorex.com/v1/senderSame envelope as Domains, Contacts and Logs. The pages below this one document each command.
Errors are reported per command. A command that fails does not stop the others, and the HTTP status stays 200.
Body parameters
commandsobject[]required1 to 20 commands, executed in order. The whole body can have up to 1 MB.
commands[].commandstringrequiredlist_senders,get_sender,create_sender,update_sender,update_sender_descriptionordelete_sender.commands[].argsobjectoptionalThe command arguments. Any value can be a
$refto the result of an earlier command.commands[].idstringoptionalYour own identifier for the result. Defaults to the index (
"0","1"…). Required if you want to use$ref.
Quick start
import axios from 'axios';
const response = await axios.post(
'https://g.sendcorex.com/v1/sender',
{
commands: [
{
command: "list_senders",
id: "all"
},
{
command: "get_sender",
id: "one",
args: {
sender_id: "K7Q2M9XR4TB8WD1ZC6NF3HJP"
}
}
]
},
{ headers: { Authorization: process.env.SENDCOREX_API_KEY } },
);
for (const result of response.data.results) {
if (result.type !== 'SUCCESS') console.error(result.id, result.code, result.message);
else console.log(result.id, result.data);
}Response
{
"type": "SUCCESS",
"results": [
{
"command": "list_senders",
"id": "all",
"type": "SUCCESS",
"took_ms": 5,
"data": {
"senders": [
{
"sender_id": "K7Q2M9XR4TB8WD1ZC6NF3HJP",
"email": "hello@acme.com",
"username": "hello",
"domain": "acme.com",
"from_name": "Acme",
"reply_to": "support@acme.com",
"description": "Product updates",
"avatar_color": "#2F6FDB",
"warmup_enabled": false,
"reputation": {
"delivered": 18420,
"bounced": 131,
"spam": 6,
"received_messages": 2210,
"total_emails": 18557,
"has_minimum_volume": true,
"delivery_rate": 99,
"bounce_rate": 1,
"spam_rate": 0,
"engagement_rate": 12,
"score": 100,
"status": "Excellent"
},
"created_at": "2026-09-02T14:40:12.530Z",
"updated_at": "2026-10-20T08:15:33.004Z"
}
]
}
},
{
"command": "get_sender",
"id": "one",
"type": "SUCCESS",
"took_ms": 2,
"data": {
"sender_id": "K7Q2M9XR4TB8WD1ZC6NF3HJP",
"email": "hello@acme.com",
"username": "hello",
"domain": "acme.com",
"from_name": "Acme",
"reply_to": "support@acme.com",
"description": "Product updates",
"avatar_color": "#2F6FDB",
"warmup_enabled": false,
"reputation": {
"delivered": 18420,
"bounced": 131,
"spam": 6,
"received_messages": 2210,
"total_emails": 18557,
"has_minimum_volume": true,
"delivery_rate": 99,
"bounce_rate": 1,
"spam_rate": 0,
"engagement_rate": 12,
"score": 100,
"status": "Excellent"
},
"created_at": "2026-09-02T14:40:12.530Z",
"updated_at": "2026-10-20T08:15:33.004Z"
}
}
]
}Response fields
typeAlways
SUCCESSwhen the request itself was accepted.results[].commandThe command that produced this result.
results[].idThe
idyou sent, or the index of the command.results[].typeSUCCESSorERROR.results[].took_msTime the command took inside the server.
results[].dataThe command output. Only present when
typeisSUCCESS.results[].code / messageThe error. Only present when
typeisERROR.
Authentication
Use the API key you create in the dashboard, under Developers → API Keys, with the scopes the commands need.
AuthorizationSend
Authorization: <api key>orAuthorization: Bearer <api key>.sender:readlist_sendersandget_sender.sender:createcreate_sender.sender:updateupdate_senderandupdate_sender_description.sender:deletedelete_sender.Mailbox tokensThe webmail token does not work here. It is rejected with
WRONG_CREDENTIAL_TYPE.Allowed IPsIf the key has an IP allowlist, requests from other IPs get
403 IP_NOT_ALLOWED.
Chaining with $ref
Create a sender and send its id to the next command in the same request.
create_sender → update_sender_description
{
"commands": [
{
"command": "create_sender",
"id": "new",
"args": {
"username": "news",
"from_name": "Acme News",
"reply_to": "news@acme.com",
"domain": "acme.com"
}
},
{
"command": "update_sender_description",
"args": {
"sender_id": {
"$ref": "new",
"path": "sender_id"
},
"description": "Monthly newsletter"
}
}
]
}Rate limits
15 requests / secondPer IP + API key. Over it, HTTP 429 with a
Retry-Afterheader.15 in flightAt most 15 requests being processed at the same time, per IP + API key.
Per command, per accountcreate_senderandupdate_sender10/min ·update_sender_description20/min ·delete_sender30/min. Over it, that command answersRATE_LIMITED.No cacheEvery call reads the database. What you get is always current.
Errors
HTTP-level errors return type, code and message. Errors marked CMD come back inside the command result, with HTTP 200.
- 400
INVALID_JSONThe body is not {"commands":[...]} or is larger than 1 MB.
- 400
INVALID_ARGSThe request has no commands or more than 20.
- 401
MISSING_AUTH_HEADERNo Authorization header was sent.
- 401
INVALID_API_KEYThe API key does not exist, was revoked or was disabled in the dashboard.
- 401
API_KEY_EXPIREDThe API key passed the expiration date set in the dashboard.
- 401
WRONG_CREDENTIAL_TYPEA mailbox token was sent. The Senders API needs a dashboard API key.
- 403
IP_NOT_ALLOWEDThe request came from an IP that is not in the allowed IPs of the key.
- 403
ACCOUNT_BLOCKEDThe account is blocked.
- 403
MISSING_SCOPEThe key has no `sender:*` scope, so no command can run.
- 429
RATE_LIMITEDMore than 15 requests/s or 15 in flight for the same IP + API key. Wait the number of seconds in Retry-After.
- 503
AUTH_UNAVAILABLEAuthentication is temporarily unavailable. Try again.
- CMD
UNKNOWN_COMMANDThe command name does not exist.
- CMD
INTERNALServer error. The detail is only written to the server log.