Recibir correos: Rutas
Run Commands
El punto de entrada único para leer y gestionar un buzón. Envía de 1 a 20 comandos en una solicitud y recibe un resultado por comando.
https://g.sendcorex.com/v1Cada acción del buzón (listar, leer, buscar, marcar, mover, enviar, responder…) es un comando que se envía a esta ruta. Las páginas debajo de esta documentan cada comando y sus argumentos.
Los errores se informan por comando. Un comando que falla no detiene a los demás, y el estado HTTP sigue siendo 200.
Parámetros del body
commandsobject[]obligatorioDe 1 a 20 comandos, ejecutados en orden.
commands[].commandstringobligatorioEl nombre del comando, por ejemplo
list_threads.commands[].argsobjectopcionalLos argumentos del comando. Cualquier valor puede ser un
$refal resultado de un comando anterior.commands[].idstringopcionalTu propio identificador para el resultado. Por defecto es el índice (
"0","1"…). Obligatorio si quieres usar$ref.
Inicio rápido
import axios from 'axios';
const response = await axios.post(
'https://g.sendcorex.com/v1',
{
commands: [
{
command: "list_folders"
},
{
command: "get_counters"
}
]
},
{ headers: { Authorization: process.env.SENDCOREX_TOKEN } },
);
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);
}Respuesta
{
"type": "SUCCESS",
"results": [
{
"command": "list_folders",
"id": "0",
"type": "SUCCESS",
"data": {
"folders": [
{
"folder": "INBOX",
"name": "INBOX",
"system": true,
"total": 12,
"unread": 3
}
]
}
},
{
"command": "get_counters",
"id": "1",
"type": "SUCCESS",
"data": {
"total": 12,
"unread": 3,
"size_bytes": 482113,
"folders": {
"INBOX": {
"total": 12,
"unread": 3,
"size_bytes": 482113
}
}
}
}
]
}Campos de la respuesta
typeSiempre
SUCCESScuando la solicitud en sí fue aceptada.results[].commandEl comando que produjo este resultado.
results[].idEl
idque enviaste, o el índice del comando.results[].typeSUCCESSoERROR.results[].dataLa salida del comando. Solo aparece cuando
typeesSUCCESS.results[].codeEl código de error. Solo aparece cuando
typeesERROR.results[].messageUn mensaje de error legible. Solo aparece cuando
typeesERROR.
Autenticación
Toda ruta de comandos necesita un access token. El token decide qué buzón se usa: ningún argumento selecciona a otro usuario.
AuthorizationEnvía
Authorization: <token>oAuthorization: Bearer <token>.Formato del tokenS.C.G.seguido de 100 caracteres. Identifica al propietario (usuario + remitente).VencimientoLos access tokens duran 1 hora. Cuando uno expira recibes
TOKEN_EXPIRED: llama a Refresh Token y repite la solicitud.
El token resuelto se guarda en caché hasta 1 hora, así que un token revocado puede seguir funcionando hasta que esa caché expire.
Acceso de solo lectura
Un token creado como Solo lectura, o una app autorizada como Solo lectura, solo puede leer el buzón.
Comandos permitidos
whoami
list_folders
get_counters
list_threads
get_thread
list_messages
get_messages
search
get_attachment
get_raw_source
list_drafts
get_draft
get_tracking
list_activity
activity_counts
list_contacts
count_contacts
get_mailbox_contact
list_segments
get_audience
check_recipients
get_delivery_status
get_contact_events
get_trust
list_trust
list_junk
blocked_junk_count
list_top_senders
get_filter_mode
list_signatures
get_conversation
list_assignees
list_conversations
list_conversation_notes
list_rules
get_rule
rule_options
test_rule
list_templates
get_template
list_labels
get_contact
list_followups
get_unsubscribe_options
list_unsubscribedCualquier comando de escritura responde READ_ONLY_ACCESS (HTTP 403 en la ruta de subida de adjuntos).
En el MCP, las tools de escritura no aparecen para una conexión de Solo lectura.
Usa un resultado anterior con $ref
Cualquier valor dentro de args puede ser {"$ref": "<id>", "path": "<path>"}. Se reemplaza por el valor encontrado en path dentro del resultado del comando con ese id. En path, * recorre una lista y aplana el resultado. Así puedes listar y leer en una sola solicitud.
Body de la solicitud
{
"commands": [
{
"command": "list_threads",
"args": {
"limit": 5
},
"id": "a"
},
{
"command": "get_messages",
"args": {
"ids": {
"$ref": "a",
"path": "threads/*/last_message_uid"
}
},
"id": "b"
}
]
}$refEl
idde un comando anterior en la misma solicitud.pathRuta separada por barras dentro de ese resultado.
*pasa por cada elemento de una lista.
Rate limits y caché
Los límites se aplican por IP + usuario + remitente. No hay cola: cuando te pasas, la solicitud se rechaza con HTTP 429 y un header Retry-After.
15 solicitudes / segundoPico de 15. Las respuestas servidas desde la caché también cuentan.
15 en cursoComo máximo 15 solicitudes procesándose al mismo tiempo.
Usa lotes en lugar de buclesEnvía hasta 20 comandos por solicitud en lugar de una solicitud por acción.
Caché de lectura: 1,5 sLa misma lectura (mismo comando y args) dentro de 1,5 segundos devuelve el mismo resultado. Aplica a
list_folders,get_counters,list_threads,list_messages,get_thread,get_messages,search,get_trustylist_trust.Deduplicación de escrituras: 1,5 sLa misma escritura repetida dentro de 1,5 segundos se ejecuta una sola vez, así que un polling que envía el mismo
replydos veces no envía dos correos.Invalidación de la cachéCualquier comando de escritura borra al instante la caché de lectura de ese buzón, así que la siguiente lectura ya ve el nuevo estado.
El correo entregado en el buzón, o los cambios hechos en el webmail, aparecen en las lecturas en menos de 1,5 segundos.
Convenciones
Estas reglas son comunes a todos los comandos.
Carpetas del sistemaINBOX,Sent,Archive,Trash,Drafts,Spam,PromotionsySnoozed. Se aceptan alias comoinbox,archived,draft,junkypromotion. Una carpeta personalizada se referencia por su slug o por su nombre.Paginaciónlimitva de 1 a 100 (por defecto 25). La respuesta tienehas_moreynext_cursor: envíanext_cursorcomocursoren la siguiente llamada.Acciones en loteLos comandos de acción aceptan
ids(una lista de hasta 100) oid(uno solo) y responden elemento por elemento conitems,ok_countyfailed_count.scopethreadse aplica a toda la conversación en la carpeta de origen.messagese aplica solo al id indicado.
Errores
Los errores a nivel HTTP devuelven type, code y message. Los errores marcados con CMD vuelven dentro del resultado del comando, con HTTP 200.
- 400
INVALID_JSONEl body no es {"commands":[...]} o tiene más de 20 comandos.
- 401
MISSING_AUTH_HEADERNo se envió ningún header Authorization.
- 401
INVALID_TOKENEl token está mal formado, es desconocido o fue revocado.
- 401
TOKEN_EXPIREDEl access token expiró. Llama a Refresh Token y repite la solicitud.
- 429
RATE_LIMITEDMás de 15 solicitudes/s o 15 en curso para la misma IP + buzón. Espera la cantidad de segundos indicada en Retry-After.
- 503
AUTH_UNAVAILABLELa autenticación no está disponible temporalmente. Inténtalo de nuevo.
- CMD
UNKNOWN_COMMANDEl nombre del comando no existe.
- CMD
INVALID_ARGSFalta un argumento obligatorio o no es válido.
- CMD
READ_ONLY_ACCESSEl token o la app tiene acceso de Solo lectura y el comando escribe. En la ruta de subida de adjuntos es HTTP 403.
- CMD
INTERNALError del servidor. El detalle solo se escribe en el log del servidor.