Senders: rutas

Run Commands

El único punto de entrada para senders. Envía de 1 a 20 comandos en una petición y recibe un resultado por comando.

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

Mismo sobre que Domains, Contacts y Logs. Las páginas debajo de esta documentan cada comando.

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 cuerpo

  • commandsobject[]obligatorio

    De 1 a 20 comandos, ejecutados en orden. Todo el cuerpo puede ocupar hasta 1 MB.

  • commands[].commandstringobligatorio

    list_senders, get_sender, create_sender, update_sender, update_sender_description o delete_sender.

  • 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, 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/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);
}

Respuesta

{
  "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"
      }
    }
  ]
}

Campos de la respuesta

  • type

    Siempre SUCCESS cuando la petición 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[].took_ms

    Tiempo que tardó el comando dentro del servidor.

  • results[].data

    La salida del comando. Solo está presente cuando type es SUCCESS.

  • results[].code / message

    El error. Solo está presente cuando type es ERROR.

Autenticación

Usa la API key que creas en el dashboard, en Developers → API Keys, con los scopes que necesitan los comandos.

  • Authorization

    Envía Authorization: <api key> o Authorization: Bearer <api key>.

  • sender:read

    list_senders y get_sender.

  • sender:create

    create_sender.

  • sender:update

    update_sender y update_sender_description.

  • sender:delete

    delete_sender.

  • Tokens de buzón

    El token del webmail no funciona aquí. Se rechaza con WRONG_CREDENTIAL_TYPE.

  • IPs permitidas

    Si la clave tiene una lista de IPs permitidas, las peticiones desde otras IPs reciben 403 IP_NOT_ALLOWED.

Encadenar con $ref

Crea un sender y pasa su id al siguiente comando en la misma petición.

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"
      }
    }
  ]
}

Límites de tasa

  • 15 peticiones / segundo

    Por IP + API key. Por encima, HTTP 429 con un header Retry-After.

  • 15 simultáneas

    Como máximo 15 peticiones procesándose a la vez, por IP + API key.

  • Por comando, por cuenta

    create_sender y update_sender 10/min · update_sender_description 20/min · delete_sender 30/min. Por encima, ese comando responde RATE_LIMITED.

  • Sin caché

    Cada llamada lee la base de datos. Lo que recibes siempre está actualizado.

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 cuerpo no es {"commands":[...]} o pesa más de 1 MB.

  • 400INVALID_ARGS

    La petición no tiene comandos o tiene más de 20.

  • 401MISSING_AUTH_HEADER

    No se envió ningún header Authorization.

  • 401INVALID_API_KEY

    La API key no existe, se revocó o se desactivó en el dashboard.

  • 401API_KEY_EXPIRED

    La API key superó la fecha de caducidad definida en el dashboard.

  • 401WRONG_CREDENTIAL_TYPE

    Se envió un token de buzón. La Senders API necesita una API key del dashboard.

  • 403IP_NOT_ALLOWED

    La petición vino de una IP que no está entre las IPs permitidas de la clave.

  • 403ACCOUNT_BLOCKED

    La cuenta está bloqueada.

  • 403MISSING_SCOPE

    La clave no tiene ningún scope `sender:*`, así que no se puede ejecutar ningún comando.

  • 429RATE_LIMITED

    Más de 15 peticiones/s o 15 simultáneas para la misma IP + API key. Espera los segundos indicados en Retry-After.

  • 503AUTH_UNAVAILABLE

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

  • CMDUNKNOWN_COMMAND

    El nombre del comando no existe.

  • CMDINTERNAL

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