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.
https://g.sendcorex.com/v1/contactsCada 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.
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[]obligatorioDe 1 a 20 comandos, ejecutados en orden. Todo el cuerpo puede ocupar hasta 1 MB.
commands[].commandstringobligatorioEl nombre del comando, por ejemplo
upsert_contacts.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, 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
typeSiempre
SUCCESScuando la petición en sí fue aceptada.results[].commandEl comando que produjo este resultado.
results[].idEl
idque enviaste, o el índice del comando.results[].typeSUCCESSoERROR.results[].took_msTiempo que tardó el comando dentro del servidor. El resto del tiempo de la petición es red.
results[].dataLa salida del comando. Solo está presente cuando
typeesSUCCESS.results[].code / messageEl error. Solo está presente cuando
typeesERROR.
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.
AuthorizationEnvía
Authorization: <api key>oAuthorization: Bearer <api key>.Tokens de buzónEl token del webmail (
S.C.G.…) no funciona aquí. Se rechaza conWRONG_CREDENTIAL_TYPE.IPs permitidasSi la clave tiene una lista de IPs permitidas, las peticiones desde otras IPs reciben
403 IP_NOT_ALLOWED.RevocaciónLas 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:readget_contacts,query_contacts,count_contacts,list_events,get_stats,list_fields,list_lists,get_list,list_members,list_segments,get_segment,run_segment.contact:createcreate_list,define_field,save_segment.contact:create + updateupsert_contacts, porque crea o actualiza.contact:updateupdate_contacts,add_tags,remove_tags,add_to_lists,remove_from_lists,set_list_subscription,set_status,set_fields,unset_fields,update_list.contact:deletedelete_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"
]
}
}
]
}$refEl
idde un comando anterior en la misma petición.pathRuta 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
}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 superioremail,domain,status,status_reason,status_at,created_at,updated_at,tags,lists,fields,statsy los campos de perfil (first_name,last_name,phone,company,locale,timezone,source).Anidadosfields.<key>,stats.<key>ylists.<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 / segundoPico de 15. Las respuestas servidas desde la caché también cuentan.
15 simultáneasComo máximo 15 peticiones procesándose a la vez.
Usa lotes en lugar de buclesUna petición puede llevar 20 comandos de 500 contactos cada uno: 10.000 contactos por petición.
Caché de lectura: 1,5 sLa 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 sLa 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
Etiquetas50 por contacto.
Listas75 por contacto.
Campos personalizados100 por cuenta.
Datos personalizados de la lista50 claves por lista.
TextoUn campo
textadmite 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 emailUn contacto pertenece a tu cuenta, no a una lista. Listas, etiquetas, campos y estado son atributos del contacto.
EmailsSe guardan en minúsculas y sin espacios.
Ana@Acme.comyana@acme.comson el mismo contacto.Mayúsculas y acentosLas 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ónLas listas que pueden crecer devuelven
has_moreynext_cursor. Envíanext_cursorcomocursoren la siguiente llamada, con los mismos argumentos restantes.EliminacionesEliminar 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.
- 400
INVALID_JSONEl cuerpo no es {"commands":[...]} o pesa más de 1 MB.
- 400
INVALID_ARGSLa petición no tiene comandos o tiene más de 20.
- 401
MISSING_AUTH_HEADERNo se envió ningún header Authorization.
- 401
INVALID_API_KEYLa API key no existe, se revocó o se desactivó en el dashboard.
- 401
API_KEY_EXPIREDLa API key superó la fecha de caducidad definida en el dashboard.
- 401
WRONG_CREDENTIAL_TYPESe envió un token de buzón (S.C.G.…). Los contactos necesitan una API key del dashboard.
- 403
IP_NOT_ALLOWEDLa petición vino de una IP que no está entre las IPs permitidas de la clave.
- 403
ACCOUNT_BLOCKEDLa cuenta está bloqueada.
- 403
MISSING_SCOPELa 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.
- 429
RATE_LIMITEDMás de 15 peticiones/s o 15 simultáneas para la misma IP + API key. Espera los segundos indicados 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
INTERNALError del servidor. El detalle solo se escribe en el log del servidor.