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.

POSThttps://g.sendcorex.com/v1
i

Cada 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.

i

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[]obligatorio

    De 1 a 20 comandos, ejecutados en orden.

  • commands[].commandstringobligatorio

    El nombre del comando, por ejemplo list_threads.

  • commands[].argsobjectopcional

    Los argumentos del comando. Cualquier valor puede ser un $ref al resultado de un comando anterior.

  • commands[].idstringopcional

    Tu 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

  • type

    Siempre SUCCESS cuando la solicitud en sí fue aceptada.

  • results[].command

    El comando que produjo este resultado.

  • results[].id

    El id que enviaste, o el índice del comando.

  • results[].type

    SUCCESS o ERROR.

  • results[].data

    La salida del comando. Solo aparece cuando type es SUCCESS.

  • results[].code

    El código de error. Solo aparece cuando type es ERROR.

  • results[].message

    Un mensaje de error legible. Solo aparece cuando type es ERROR.

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.

  • Authorization

    Envía Authorization: <token> o Authorization: Bearer <token>.

  • Formato del token

    S.C.G. seguido de 100 caracteres. Identifica al propietario (usuario + remitente).

  • Vencimiento

    Los 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_unsubscribed
!

Cualquier comando de escritura responde READ_ONLY_ACCESS (HTTP 403 en la ruta de subida de adjuntos).

i

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"
    }
  ]
}
  • $ref

    El id de un comando anterior en la misma solicitud.

  • path

    Ruta 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 / segundo

    Pico de 15. Las respuestas servidas desde la caché también cuentan.

  • 15 en curso

    Como máximo 15 solicitudes procesándose al mismo tiempo.

  • Usa lotes en lugar de bucles

    Envía hasta 20 comandos por solicitud en lugar de una solicitud por acción.

  • Caché de lectura: 1,5 s

    La 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_trust y list_trust.

  • Deduplicación de escrituras: 1,5 s

    La misma escritura repetida dentro de 1,5 segundos se ejecuta una sola vez, así que un polling que envía el mismo reply dos 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.

i

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 sistema

    INBOX, Sent, Archive, Trash, Drafts, Spam, Promotions y Snoozed. Se aceptan alias como inbox, archived, draft, junk y promotion. Una carpeta personalizada se referencia por su slug o por su nombre.

  • Paginación

    limit va de 1 a 100 (por defecto 25). La respuesta tiene has_more y next_cursor: envía next_cursor como cursor en la siguiente llamada.

  • Acciones en lote

    Los comandos de acción aceptan ids (una lista de hasta 100) o id (uno solo) y responden elemento por elemento con items, ok_count y failed_count.

  • scope

    thread se aplica a toda la conversación en la carpeta de origen. message se 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.

  • 400INVALID_JSON

    El body no es {"commands":[...]} o tiene más de 20 comandos.

  • 401MISSING_AUTH_HEADER

    No se envió ningún header Authorization.

  • 401INVALID_TOKEN

    El token está mal formado, es desconocido o fue revocado.

  • 401TOKEN_EXPIRED

    El access token expiró. Llama a Refresh Token y repite la solicitud.

  • 429RATE_LIMITED

    Más de 15 solicitudes/s o 15 en curso para la misma IP + buzón. Espera la cantidad de segundos indicada en Retry-After.

  • 503AUTH_UNAVAILABLE

    La autenticación no está disponible temporalmente. Inténtalo de nuevo.

  • CMDUNKNOWN_COMMAND

    El nombre del comando no existe.

  • CMDINVALID_ARGS

    Falta un argumento obligatorio o no es válido.

  • CMDREAD_ONLY_ACCESS

    El token o la app tiene acceso de Solo lectura y el comando escribe. En la ruta de subida de adjuntos es HTTP 403.

  • CMDINTERNAL

    Error del servidor. El detalle solo se escribe en el log del servidor.