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
POSThttps://g.sendcorex.com/v1/contacts

Có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. 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. 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. 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. 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:read

    Leer contactos, listas, campos, segmentos, eventos y estadísticas.

  • contact:create

    Crear listas, campos y segmentos. Upsert también lo necesita, para crear contactos nuevos.

  • contact:update

    Actualizar contactos, etiquetas, estado, campos y pertenencia a listas.

  • contact:delete

    Eliminar contactos, listas, campos y segmentos.

i

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

Global. Un contacto dado de baja, rebotado, que se quejó o bloqueado no puede recibir envíos en ninguna lista.

lists

Pertenencia y suscripción por lista. Alguien puede salir de una lista y seguir en las demás.

sendable

Suscrito a la lista y con estado subscribed. Es a quien envían las campañas.

stats

Enví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 Contacts

Respeta un enlace de baja

Da de baja de una lista con Set List Subscription, o de todo con Set Status.

Set List Subscription

Encuentra clientes comprometidos

Consulta por lista, etiqueta y last_open_at, ordenado por open_rate. Guárdalo como segmento para reutilizarlo.

Query Contacts

Exporta una lista

Recorre List Members con sendable_only y selecciona solo los campos que necesitas, 5.000 miembros por página.

List Members

Referencia completa

Todo lo marcado como CMD es un comando enviado a través de POST /v1/contacts, hasta 20 por petición.