Logs: Routes
Run Commands
The single entry point for delivery logs. Send 1 to 20 commands in one request and get one result per command.
https://g.sendcorex.com/v1/logsIt is the same envelope as Contacts: every read is a command sent to this route. The pages below this one document each command and its arguments.
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_logsorget_logs.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/logs',
{
commands: [
{
command: "list_logs",
id: "bounces",
args: {
status: "bounced",
limit: 20
}
},
{
command: "get_logs",
id: "one",
args: {
id: "3f2a1b4c-8e9d-4f7a-b2c3-1a2b3c4d5e6f"
}
}
]
},
{ 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_logs",
"id": "bounces",
"type": "SUCCESS",
"took_ms": 21,
"data": {
"logs": [
{
"id": "9b7e4c21-0d3a-4e8f-a6b1-5c2d7e9f1a30",
"to": "old.address@gmail.com",
"from": "noreply@yourdomain.com",
"domain": "gmail.com",
"from_domain": "yourdomain.com",
"subject": "Your order #1042 has shipped",
"status": "bounced",
"status_code": 6,
"response": "550 5.1.1 The email account that you tried to reach does not exist.",
"message": null,
"blocked": false,
"block_reason": null,
"retries": 0,
"tracking_id": "7CK-JDL-Z2M-20261017",
"sent_at": "2026-10-17T05:58:44.031Z",
"updated_at": "2026-10-17T05:58:45.600Z"
}
],
"count": 1,
"has_more": false,
"next_cursor": null,
"partial": false
}
},
{
"command": "get_logs",
"id": "one",
"type": "SUCCESS",
"took_ms": 9,
"data": {
"logs": [
{
"id": "3f2a1b4c-8e9d-4f7a-b2c3-1a2b3c4d5e6f",
"to": "ana@acme.com",
"from": "noreply@yourdomain.com",
"domain": "acme.com",
"from_domain": "yourdomain.com",
"subject": "Your order #1042 has shipped",
"status": "delivered",
"status_code": 2,
"response": "250 2.0.0 OK 1760684401 a1si123456",
"message": null,
"blocked": false,
"block_reason": null,
"retries": 0,
"tracking_id": "7CK-JDL-Y1L-20261017",
"sent_at": "2026-10-17T06:00:01.204Z",
"updated_at": "2026-10-17T06:00:02.913Z"
}
],
"not_found": []
}
}
]
}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. The rest of the request time is network.
results[].dataThe command output. Only present when
typeisSUCCESS.results[].code / messageThe error. Only present when
typeisERROR.
Authentication
Logs use the API key you create in the dashboard, under Developers → API Keys, with the logs:read scope. It is the same kind of key used to send email and to manage contacts.
AuthorizationSend
Authorization: <api key>orAuthorization: Bearer <api key>.logs:readThe only scope logs need. It is read-only: nothing on this route changes data.
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.RevokingKeys are cached for 60 seconds, so a revoked key stops working within a minute. The expiration date is checked on every request.
Use a previous result with $ref
Any value inside args can be {"$ref": "<id>", "path": "<path>"}. It is replaced by the value found at path in the result of the command with that id. In path, * walks a list. This request lists the latest bounces and reads their bodies, in one round trip.
Request body
{
"commands": [
{
"command": "list_logs",
"id": "b",
"args": {
"status": "bounced",
"limit": 10
}
},
{
"command": "get_logs",
"args": {
"ids": {
"$ref": "b",
"path": "logs/*/id"
},
"include_content": true
}
}
]
}What is in the logs
Every sendEach email you send gets one log, which is updated as the delivery gets a result.
60 daysLogs are kept for 60 days. Older ones are gone, and their ids come back in
not_found.No warm-upEmails sent by inbox warm-up never show up, so polling only returns your real traffic.
No body by defaultLists never carry the HTML. Get Logs returns it only with
include_content: true.
Rate limits and cache
Limits apply per IP + API key. There is no queue: when you go over, the request is rejected with HTTP 429 and a Retry-After header.
15 requests / secondPeak of 15. Responses served from the cache count too.
15 in flightAt most 15 requests being processed at the same time. Walking many pages in parallel is the usual way to hit it: walk them one after the other.
Read cache: 1.5 sThe same read (same command and args) within 1.5 seconds returns the same result, and identical reads in flight share one query. Polling every few seconds is fine.
Cursors
List Logs returns next_cursor while there is more. It is opaque: pass it back as it is, with the same filters.
next_cursor
{
"has_more": true,
"next_cursor": "MDAwMDAwMDA4MzowOjgyMzkzMTU5OTg3OTU6M2YyYTFi",
"partial": false
}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. Logs need 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 does not have `logs:read`, 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.