Contactos: rutas

Run Commands

El único punto de entrada para contactos, listas, campos personalizados y segmentos. Envía de 1 a 20 comandos en una petición y recibe un resultado por comando.

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

Cada acción (importar, etiquetar, consultar, dar de baja, crear una lista…) es un comando enviado a esta ruta. Las páginas debajo de esta documentan cada comando y sus argumentos.

i

Los errores se informan por comando, y las acciones en lote informan por email. 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

    El nombre del comando, por ejemplo upsert_contacts.

  • 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/contacts',
  {
    commands: [
      {
        command: "list_lists"
      },
      {
        command: "get_stats"
      }
    ]
  },
  { 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_lists",
      "id": "0",
      "type": "SUCCESS",
      "took_ms": 6,
      "data": {
        "lists": [
          {
            "list_id": "customers",
            "name": "Customers",
            "description": "Everyone who bought at least once",
            "source": "checkout",
            "status": "ready",
            "custom": {
              "origin": "checkout",
              "year": 2026
            },
            "created_at": "2026-10-01T10:00:00.000Z",
            "updated_at": "2026-10-12T15:22:41.000Z",
            "stats": {
              "total": 1834,
              "ok": 1790,
              "opened": 912,
              "clicked": 233
            }
          }
        ]
      }
    },
    {
      "command": "get_stats",
      "id": "1",
      "type": "SUCCESS",
      "took_ms": 9,
      "data": {
        "total": 2040,
        "status": {
          "subscribed": 1951,
          "unsubscribed": 61,
          "bounced": 22,
          "complained": 3,
          "blocked": 3
        },
        "lists": {
          "customers": {
            "total": 1834,
            "ok": 1790,
            "opened": 912,
            "clicked": 233
          }
        },
        "tags": {
          "customer": 1834,
          "vip": 120
        }
      }
    }
  ]
}

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. El resto del tiempo de la petición es red.

  • 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

Los contactos usan la API key que creas en el dashboard, en Developers → API Keys. Es el mismo tipo de clave que se usa para enviar emails, y no caduca salvo que le pongas una fecha de caducidad.

  • Authorization

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

  • Tokens de buzón

    El token del webmail (S.C.G.…) 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.

  • Revocación

    Las claves se guardan en caché 60 segundos, así que una clave revocada deja de funcionar en menos de un minuto. La fecha de caducidad se comprueba en cada petición.

!

Guarda la clave en tu servidor. Cualquiera que la tenga puede leer y modificar tus contactos.

Scopes

Cada comando necesita un scope en la clave. Cuando falta un scope, solo ese comando falla con MISSING_SCOPE; el resto de la petición se ejecuta con normalidad. Una clave sin ningún scope contact:* recibe 403 MISSING_SCOPE antes de ejecutar ningún comando.

  • contact:read

    get_contacts, query_contacts, count_contacts, list_events, get_stats, list_fields, list_lists, get_list, list_members, list_segments, get_segment, run_segment.

  • contact:create

    create_list, define_field, save_segment.

  • contact:create + update

    upsert_contacts, porque crea o actualiza.

  • contact:update

    update_contacts, add_tags, remove_tags, add_to_lists, remove_from_lists, set_list_subscription, set_status, set_fields, unset_fields, update_list.

  • contact:delete

    delete_contacts, delete_list, delete_field, delete_segment.

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. Esta petición encuentra todos los contactos del plan pro o business y los etiqueta, en un solo viaje.

Cuerpo de la petición

{
  "commands": [
    {
      "command": "query_contacts",
      "id": "q",
      "args": {
        "where": {
          "fields": {
            "plan": {
              "in": [
                "pro",
                "business"
              ]
            }
          }
        },
        "select": [
          "email"
        ]
      }
    },
    {
      "command": "add_tags",
      "args": {
        "emails": {
          "$ref": "q",
          "path": "contacts/*/email"
        },
        "tags": [
          "premium"
        ]
      }
    }
  ]
}
  • $ref

    El id de un comando anterior en la misma petición.

  • path

    Ruta separada por barras dentro de ese resultado. * recorre todos los elementos de una lista.

Acciones en lote

Las acciones reciben emails (hasta 500) o email (solo uno) y responden email por email. Un email erróneo falla por su cuenta, sin detener a los demás.

data de una acción en lote

{
  "items": [
    {
      "id": "ana@acme.com",
      "ok": true,
      "data": {
        "changed": true
      }
    },
    {
      "id": "x@y.com",
      "ok": false,
      "code": "NOT_FOUND",
      "message": "contact not found"
    }
  ],
  "ok_count": 1,
  "failed_count": 1
}
i

changed: false significa que el contacto ya estaba así, así que no se escribió nada. Envía return_contacts: true para recibir el contacto completo en cada elemento.

Pide solo lo que necesitas

Sin select, cada contacto vuelve completo. Con él, solo vuelven las partes que nombres, y email siempre vuelve. Funciona en get_contacts, query_contacts, run_segment y list_members con hydrate. Una consulta solo de emails se responde desde el índice y es la lectura más rápida que hay.

Cuerpo de la petición

{
  "commands": [
    {
      "command": "query_contacts",
      "args": {
        "where": {
          "list": "customers",
          "sendable": true
        },
        "select": [
          "first_name",
          "status",
          "fields.plan",
          "stats.open_count"
        ]
      }
    }
  ]
}
  • Nivel superior

    email, domain, status, status_reason, status_at, created_at, updated_at, tags, lists, fields, stats y los campos de perfil (first_name, last_name, phone, company, locale, timezone, source).

  • Anidados

    fields.<key>, stats.<key> y lists.<list_id> devuelven solo esa parte. Pedir el nivel superior completo (fields) prevalece sobre sus subclaves.

Límites de tasa y caché

Los límites se aplican por IP + API key. No hay cola: cuando te pasas, la petición se rechaza con HTTP 429 y un header Retry-After.

  • 15 peticiones / segundo

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

  • 15 simultáneas

    Como máximo 15 peticiones procesándose a la vez.

  • Usa lotes en lugar de bucles

    Una petición puede llevar 20 comandos de 500 contactos cada uno: 10.000 contactos por petición.

  • Caché de lectura: 1,5 s

    La misma lectura (mismo comando y args) en menos de 1,5 segundos devuelve el mismo resultado, y las lecturas idénticas en curso comparten una sola consulta.

  • Deduplicación de escrituras: 1,5 s

    La misma escritura repetida en menos de 1,5 segundos devuelve el primer resultado sin volver a escribir, así que un doble clic no importa dos veces.

  • Invalidación de la caché

    Cualquier escritura borra tu caché de lectura al instante, así que la siguiente lectura ve el estado nuevo.

Límites

  • Etiquetas

    50 por contacto.

  • Listas

    75 por contacto.

  • Campos personalizados

    100 por cuenta.

  • Datos personalizados de la lista

    50 claves por lista.

  • Texto

    Un campo text admite hasta 2.000 caracteres. Los campos de perfil (first_name…) admiten hasta 256.

Convenciones

Estas reglas son comunes a todos los comandos.

  • Un contacto por email

    Un contacto pertenece a tu cuenta, no a una lista. Listas, etiquetas, campos y estado son atributos del contacto.

  • Emails

    Se guardan en minúsculas y sin espacios. Ana@Acme.com y ana@acme.com son el mismo contacto.

  • Mayúsculas y acentos

    Las etiquetas, las opciones de enum y la comparación de texto ignoran mayúsculas y acentos: "são paulo" coincide con "Sao Paulo". Las etiquetas se guardan normalizadas.

  • Paginación

    Las listas que pueden crecer devuelven has_more y next_cursor. Envía next_cursor como cursor en la siguiente llamada, con los mismos argumentos restantes.

  • Eliminaciones

    Eliminar una lista o un campo surte efecto al instante; los valores se quitan de los contactos en segundo plano (purging: true).

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 (S.C.G.…). Los contactos necesitan 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 contact:*, así que no se puede ejecutar ningún comando. Cuando solo falta un scope, solo falla ese comando, con HTTP 200.

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