Contactos
Gestiona tu audiencia con la API
Mantén tus contactos sincronizados con tu aplicación. Importa miles a la vez, etiquétalos, guarda tus propios campos, organízalos en listas y encuentra exactamente a quién escribir, todo a través de un solo endpoint.
- REST
- JSON
- En lote, hasta 10.000 por petición
- Listas, etiquetas y campos
- Segmentos
https://g.sendcorex.com/v1/contactsCómo funciona
Un contacto por email
Un contacto pertenece a tu cuenta, no a una lista. Listas, etiquetas, campos personalizados y estado son atributos de ese único contacto, así que nada se duplica.
Un endpoint para todo
Importar, etiquetar, consultar, dar de baja, gestionar listas y segmentos: cada acción es un comando enviado a POST /v1/contacts. Hasta 20 comandos por petición.
Pensado para volumen
Cada acción acepta hasta 500 emails y responde email por email. Una fila errónea falla por su cuenta; el resto del lote sigue adelante.
Primeros pasos
Cuatro pasos, y solo el primero es obligatorio antes de tu primera petición.
- 1
Crea una API key
En el dashboard, abre Developers → API Keys y crea una clave. Dale los scopes de contactos que necesite tu aplicación.
El token del webmail no funciona aquí. Los contactos usan la misma API key del dashboard que usas para enviar emails.
- 2
Elige los scopes
Las integraciones de solo lectura solo necesitan contact:read. Una sincronización que importa y actualiza necesita contact:create y contact:update.
- 3
Define tus campos y listas
Crea los campos personalizados que quieres guardar (plan, ciudad, cumpleaños…) y las listas a las que envías. También puedes hacerlo desde el dashboard.
- 4
Importa y consulta
Envía tus contactos con Upsert Contacts y luego encuéntralos con Query Contacts.
Scopes
Cada comando necesita un scope en la clave. Cuando falta uno, solo ese comando falla con MISSING_SCOPE; el resto de la petición se ejecuta igualmente.
contact:readLeer contactos, listas, campos, segmentos, eventos y estadísticas.
contact:createCrear listas, campos y segmentos. Upsert también lo necesita, para crear contactos nuevos.
contact:updateActualizar contactos, etiquetas, estado, campos y pertenencia a listas.
contact:deleteEliminar contactos, listas, campos y segmentos.
La lista completa, comando por comando, está en Run Commands. Cada página de comando también indica qué scope necesita.
El contacto
Toda lectura devuelve los contactos con esta forma. Solo escribes las partes que te interesan.
{
"email": "ana@acme.com",
"domain": "acme.com",
"first_name": "Ana",
"last_name": "Costa",
"phone": null,
"company": "Acme",
"locale": "pt-BR",
"timezone": "America/Sao_Paulo",
"source": "checkout",
"status": "subscribed",
"status_reason": null,
"status_at": "2026-10-13T06:05:08.323Z",
"created_at": "2026-10-13T06:05:08.323Z",
"updated_at": "2026-10-14T09:12:40.118Z",
"tags": [
"customer",
"vip"
],
"lists": {
"customers": {
"subscribed": true,
"sendable": true,
"added_at": "2026-10-13T06:05:08.323Z",
"unsubscribed_at": null
}
},
"fields": {
"plan": "pro",
"age": 31,
"city": "São Paulo"
},
"stats": {
"sent_count": 12,
"open_count": 7,
"click_count": 2,
"bounce_count": 0,
"complaint_count": 0,
"open_rate": 0.58,
"click_rate": 0.17,
"first_open_at": "2026-10-13T08:41:02.000Z",
"last_open_at": "2026-10-14T21:03:55.000Z",
"last_click_at": "2026-10-14T21:04:10.000Z",
"last_sent_at": "2026-10-14T20:58:31.000Z"
}
}statusGlobal. Un contacto dado de baja, rebotado, que se quejó o bloqueado no puede recibir envíos en ninguna lista.
listsPertenencia y suscripción por lista. Alguien puede salir de una lista y seguir en las demás.
sendableSuscrito a la lista y con estado subscribed. Es a quien envían las campañas.
statsEnvíos, aperturas y clics del tracking. Solo lectura, y puedes filtrar y ordenar por ellos.
Tu primera petición
Importa dos contactos y vuelve a leerlos, en una sola petición. Reemplaza SENDCOREX_API_KEY por tu API key.
curl -X POST 'https://g.sendcorex.com/v1/contacts' \
-H "Authorization: $SENDCOREX_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
"commands": [
{ "command": "upsert_contacts", "args": {
"tags": ["imported"],
"contacts": [
{ "email": "ana@acme.com", "first_name": "Ana", "company": "Acme" },
{ "email": "bob@gmail.com", "first_name": "Bob" }
]
} },
{ "command": "query_contacts", "args": { "where": { "tags": { "has": "imported" } } } }
]
}' Recibes un resultado por comando. El primero indica cuántos contactos se created; el segundo los devuelve. Ejecútalo otra vez y no se escribe nada: ambas filas vuelven con changed: false. La misma petición en 8 lenguajes está en Upsert Contacts.
Tareas comunes
Sincroniza los registros de tu aplicación
Haz upsert del contacto con list_id en cada registro. Reenviar los mismos datos no escribe nada, así que también puedes llamarlo en cada inicio de sesión.
Upsert ContactsRespeta un enlace de baja
Da de baja de una lista con Set List Subscription, o de todo con Set Status.
Set List SubscriptionEncuentra clientes comprometidos
Consulta por lista, etiqueta y last_open_at, ordenado por open_rate. Guárdalo como segmento para reutilizarlo.
Query ContactsExporta una lista
Recorre List Members con sendable_only y selecciona solo los campos que necesitas, 5.000 miembros por página.
List MembersReferencia completa
Todo lo marcado como CMD es un comando enviado a través de POST /v1/contacts, hasta 20 por petición.
Rutas
1Contactos
4Búsqueda
2Etiquetas, estado y campos
5Listas
9- CMDList ListsTodas las listas, con contadores
- CMDGet ListUna lista y sus contadores
- CMDCreate ListTu propio id o uno generado
- CMDUpdate ListNombre, descripción, datos personalizados
- CMDDelete ListLos contactos se conservan
- CMDList MembersRecorre una lista, solo sendable
- CMDAdd To ListsUnirse a una o más listas
- CMDRemove From ListsSalir de una o más listas
- CMDSet List SubscriptionDar de baja de una lista