Conexiones de CRM

#Visión general

Una conexión de CRM mantiene los contactos de Postal y las personas de tu CRM sincronizados, en los dos sentidos y sin bucles. Lo que la persona hace en el CRM (un contacto nuevo, un negocio que cambia de etapa) llega a Postal como contacto, etiqueta, propiedad y evento, y puede iniciar una automatización. Lo que sucede en Postal (un contacto creado o modificado, un correo abierto, con clic, respondido o rebotado) vuelve al CRM como datos de la persona y como nota en su línea de tiempo.

Las tres conexiones nativas usan el token que pegas (sin OAuth) y leen la API del CRM por ti. La conexión por webhook sirve para cualquier CRM o sistema que envíe y reciba webhooks; tiene su propia página.

Las integraciones con apps (Stripe, Supabase, Clerk, Auth0 y Firebase) usan las mismas conexiones, pero se cuentan aparte, en app_integrations, y no sincronizan de vuelta.

#Crear una conexión

En el panel, abre Integraciones › CRM, elige el CRM y pega las credenciales. Se guardan cifradas y no vuelven a mostrarse: la API devuelve solo los nombres de los campos guardados. Usa Probar conexión para comprobar el acceso. Por la API, es POST /crm-connections, con una clave de acceso total.

curl -X POST https://api.postal.so/crm-connections \
  -H "Authorization: Bearer $POSTAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "hubspot",
    "name": "HubSpot",
    "credentials": {
      "access_token": "pat-na1-…",
      "client_secret": "…"
    },
    "settings": {
      "direction": "both"
    }
  }'

const response = await fetch('https://api.postal.so/crm-connections', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.POSTAL_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    provider: 'hubspot',
    name: 'HubSpot',
    credentials: {
      access_token: 'pat-na1-…',
      client_secret: '…',
    },
    settings: {
      direction: 'both',
    },
  }),
});

const data = await response.json();

import os
import requests

response = requests.post(
    "https://api.postal.so/crm-connections",
    headers={"Authorization": f"Bearer {os.environ['POSTAL_API_KEY']}"},
    json={
        "provider": "hubspot",
        "name": "HubSpot",
        "credentials": {
            "access_token": "pat-na1-…",
            "client_secret": "…",
        },
        "settings": {
            "direction": "both",
        },
    },
    timeout=10,
)

data = response.json()

$client = new \GuzzleHttp\Client(['base_uri' => 'https://api.postal.so']);

$response = $client->post('crm-connections', [
    'headers' => ['Authorization' => 'Bearer '.getenv('POSTAL_API_KEY')],
    'json' => [
        'provider' => 'hubspot',
        'name' => 'HubSpot',
        'credentials' => [
            'access_token' => 'pat-na1-…',
            'client_secret' => '…',
        ],
        'settings' => [
            'direction' => 'both',
        ],
    ],
]);

$data = json_decode($response->getBody(), true);

{
  "object": "crm_connection",
  "id": "019a2b3c-4d5e-7f60-8a9b-0c1d2e3f4a5b",
  "provider": "hubspot",
  "name": "HubSpot",
  "status": "active",
  "settings": {
    "direction": "both",
    "field_mappings": [],
    "stage": null,
    "inbound": {
      "items_path": null,
      "event_field": null,
      "allow_token": false
    },
    "outbound": {
      "url": null,
      "events": [
        "contact.created",
        "contact.updated",
        "contact.deleted",
        "email.opened",
        "email.clicked",
        "email.replied",
        "email.bounced",
        "email.complained"
      ]
    },
    "skip_sources": []
  },
  "credentials": ["access_token", "client_secret"],
  "source": "crm:019a2b3c-4d5e-7f60-8a9b-0c1d2e3f4a5b",
  "webhook_url": "https://api.postal.so/integrations/crm/019a2b3c-4d5e-7f60-8a9b-0c1d2e3f4a5b/webhook",
  "webhook_secret": "whsec_c2VncmVkby1kZS1leGVtcGxvLTEyMzQ1Ng==",
  "last_sync_at": null,
  "last_error": null,
  "last_error_at": null,
  "created_at": "2026-10-26T14:00:00.000000Z",
  "updated_at": "2026-10-26T14:00:00.000000Z"
}

• provider: hubspot, pipedrive, rdstation_crm o generic (el webhook). Las credenciales de cada uno están más abajo.
• status empieza en active. paused (PATCH) deja de recibir y de enviar sin borrar nada; error es solo un aviso de que el último envío falló definitivamente y vuelve a active con el primer envío que funcione.
• webhook_url es donde el CRM entrega los cambios; webhook_secret (whsec_…) es el secreto que autentica la entrega. Aparecen al crear, al consultar una conexión y al generar un secreto nuevo, no en la lista.
• source (crm:<id>) es el origen de todo lo que la conexión cambia en los contactos.

#Qué se sincroniza y en qué sentido

settings.direction elige el sentido: both (por defecto), inbound (solo del CRM a Postal) u outbound (solo de Postal al CRM). En una conexión solo de envío, el webhook del CRM responde 409 connection_paused; en una solo de recepción, Postal no envía nada.

Del CRM a Postal

• Cada persona se convierte en un contacto creado o actualizado. Postal reconoce el contacto por el vínculo con el registro del CRM, después por el external_id y por último por el correo; por eso un cambio de correo en el CRM actualiza el mismo contacto.
• Los campos mapeados se convierten en nombre, propiedades y etiquetas (consulta Mapear campos y etapas). Quien está en la lista de supresión no se convierte en contacto (la entrada queda como skipped).
• Quien canceló la suscripción nunca es vuelto a suscribir por un CRM: unsubscribed: false no deshace una cancelación (solo la API de contactos, con la prueba del nuevo consentimiento).
• Un evento del CRM, cuando el mapeo nombra uno (inbound.event_field), se guarda en el contacto y puede iniciar una automatización con el disparador de evento.
• Las eliminaciones en el CRM no borran el contacto en Postal.

De Postal al CRM

Postal envía los cambios que el CRM suscribió en settings.outbound.events. El valor predeterminado es:

Los eventos son los mismos de los webhooks de Postal. Cualquier otro nombre en outbound.events da 422.

El texto de las notas está siempre en portugués de Brasil, como lo leen las personas del CRM (por ejemplo, “Postal: E-mail aberto”, “Assunto: …”). Los nombres de campos que Postal guarda en el CRM no cambian con el idioma.

Sincronizar ahora

El botón Sincronizar ahora (POST /crm-connections/{id}/sync) se ejecuta en segundo plano: lee las personas del CRM, página a página (y, si hay mapeo de etapas, los negocios abiertos), y después envía todos los contactos de Postal, según el sentido. Cada persona aparece en el registro, y una entrada sync resume cuántas personas se importaron y enviaron y cuántas fallaron. Sirve para la primera carga, para recuperar lo que un webhook perdió o cuando el CRM no puede enviar webhooks.

#Mapear campos y etapas

Sin mapeo, Postal lee y escribe en su formato propio. En las conexiones nativas, el correo, el nombre, el apellido y el ID del registro ya vienen enlazados, y lo que mapeas se suma a ellos. Cada mapeo enlaza un campo del CRM con un campo de Postal, con un sentido propio (both, inbound u outbound):

El campo del CRM es una ruta al estilo JSONPath, de hasta 255 caracteres, con un subconjunto pequeño: $.person.email (o person.email), items[0].name, $.data.items[*] (todos los elementos de una lista) y $ (el documento completo). Una ruta que no existe lee null, y el campo se ignora (salvo nombre y apellido, que quedan vacíos). En las conexiones nativas, las rutas apuntan al registro que Postal construye a partir del CRM (por ejemplo, $.properties.company en HubSpot y $.custom.<chave> en Pipedrive y en RD Station CRM); GET /crm-connections/{id}/fields lista los campos del CRM que puedes elegir, con el tipo.

Etapas del embudo

Cuando un negocio cambia de etapa, su persona recibe una propiedad y/o una etiqueta de Postal, y se puede disparar una automatización con ese cambio. En settings.stage, crm_field y pipeline_field indican dónde están la etapa y el embudo (en las conexiones nativas, $.deal.stage y $.deal.pipeline ya son el valor por defecto), y cada elemento de mappings enlaza una stage (y, opcionalmente, un pipeline) con una property_key con property_value, con una tag o con las dos. Los nombres se comparan sin distinguir mayúsculas de minúsculas. Sin property_value, la propiedad recibe el nombre de la etapa. Al enviar, Postal no mueve negocios en el CRM. GET /crm-connections/{id}/stages lista las etapas de cada embudo.

{
  "settings": {
    "direction": "both",
    "field_mappings": [
      {
        "crm_field": "$.properties.company",
        "postal_field": "properties.company",
        "direction": "both"
      },
      {
        "crm_field": "$.properties.hs_lead_status",
        "postal_field": "tags",
        "direction": "inbound"
      }
    ],
    "stage": {
      "crm_field": "$.deal.stage",
      "pipeline_field": "$.deal.pipeline",
      "mappings": [
        {
          "stage": "Closed won",
          "pipeline": "Sales",
          "property_key": "lifecycle",
          "property_value": "customer",
          "tag": "customer"
        }
      ]
    },
    "outbound": {
      "events": [
        "contact.created",
        "contact.updated",
        "email.opened",
        "email.clicked",
        "email.replied"
      ]
    },
    "skip_sources": [
      "my-app"
    ]
  }
}

En este ejemplo, el campo company de HubSpot va y vuelve a la propiedad company de Postal, el estado de lead solo entra como etiqueta, y un negocio en “Closed won” del embudo “Sales” marca a la persona con lifecycle = customer y la etiqueta customer. Las propiedades company y lifecycle deben existir antes. Solo los eventos listados salen hacia el CRM, y los cambios que vienen de my-app no vuelven a él.

#Sin bucles

Dos conexiones que se alimentan entre sí podrían intercambiar el mismo cambio para siempre. Postal lo evita de dos maneras:

• Todo lo que una conexión cambia en un contacto lleva el origen crm:<id> (last_change_source), y esa conexión no reenvía el cambio que ella misma hizo. Las otras conexiones del equipo reciben el cambio con normalidad.
• settings.skip_sources lista orígenes cuyos cambios la conexión no envía (hasta 20; letras minúsculas, números, ., _, : y -; un * al final vale como prefijo). Úsalo para el sistema que escribe en Postal y también en el CRM, por ejemplo tu app, que envía contactos por la API con la etiqueta de origen my-app, y crm:* para ignorar todas las conexiones de CRM.

#Conexiones nativas

Las tres funcionan del mismo modo: Postal llama a la API del CRM con tu token (con un tiempo límite de 10 segundos, sin seguir redirecciones), busca a la persona por el vínculo guardado y después por el correo, y crea o actualiza el registro. Si un CRM responde 429, se espera el tiempo que pida, y un 5xx se reintenta. Las personas sin correo se ignoran. El mensaje de error del CRM aparece en el registro y nunca incluye el token.

Para recibir cambios del CRM hay que configurar el webhook en el propio CRM, con la URL de la conexión (webhook_url); sin webhook, la conexión aún envía datos y lee el CRM cuando pides Sincronizar ahora. Cada CRM autentica el webhook de una forma:

Una firma o credencial incorrecta responde 401 invalid_signature. Si la seguridad del secreto se ve comprometida, genera otro con POST /crm-connections/{id}/webhook-secret/rotate y actualiza el webhook en el CRM: el antiguo deja de valer al instante.

HubSpot

• Credenciales: access_token (obligatorio) y client_secret (opcional, solo para webhooks). En HubSpot, ve a Configuración › Integraciones › Aplicaciones privadas y crea una aplicación con permiso de contactos (lectura y escritura), negocios (lectura) y esquemas de contactos y de negocios (lectura); copia el token de acceso. El client secret es el de la aplicación que firma las notificaciones.
• Webhook: en la aplicación, suscríbete a contactos (creación y cambio de propiedad) y a negocios (creación y cambio de etapa) con la URL de la conexión. Las eliminaciones y las fusiones se ignoran.
• Campos: el registro es el de HubSpot, {"id", "properties": {…}}, así que las rutas son $.properties.<nome interno>. Postal lee las propiedades que mapeas, además de correo, nombre, apellido y teléfono. Para negocios, $.deal.stage, $.deal.pipeline, $.deal.status, $.deal.title y $.deal.value.
• Envío: el contacto se actualiza por el vínculo, o se busca por el correo y se crea si no existe. La actividad de correo se convierte en una nota asociada al contacto.

Pipedrive

• Credenciales: api_token y company_domain. En Pipedrive, abre el menú de la cuenta › Preferencias personales › API y copia el token personal. La dirección de la cuenta es solo la primera parte de la dirección que usas en el navegador: minhaempresa en minhaempresa.pipedrive.com (letras minúsculas, números y guiones).
• Webhook: en Herramientas y apps › Webhooks, crea un webhook para personas y otro para negocios (todos los eventos), con la URL de la conexión y la autenticación HTTP básica indicada arriba. Las eliminaciones se ignoran. Un cambio en un negocio lee a su persona y los nombres de la etapa y del embudo.
• Campos: $.email, $.first_name, $.last_name, $.name, $.phone, $.organization, $.id, los campos personalizados de la persona en $.custom.<chave> y, para negocios, $.deal.stage, $.deal.pipeline, $.deal.status, $.deal.title y $.deal.value.
• Envío: la persona se actualiza por el vínculo o se busca por el correo y se crea si no existe; el correo y el teléfono nuevos entran como principales sin borrar los otros. La actividad de correo se convierte en una nota en la persona.

RD Station CRM

• Credenciales: token, el token de la instancia. En RD Station CRM, abre el menú de la cuenta › Configuración › Integraciones › Token de la API.
• Webhook: crea un webhook para contactos y otro para negociaciones con la URL de la conexión incluyendo el ?token= (la pantalla de la conexión muestra la URL lista). Las eliminaciones se ignoran.
• Campos: $.email, $.first_name, $.last_name, $.name, $.phone, $.title, $.organization, $.id, los campos personalizados del contacto en $.custom.<id> y, para negociaciones, $.deal.stage, $.deal.pipeline, $.deal.status, $.deal.title y $.deal.value.
• Envío: el contacto se actualiza por el vínculo o se busca por el correo y se crea si no existe. La actividad de correo se convierte en una actividad en la negociación abierta del contacto; sin negociación, una línea en las anotaciones del contacto (las más antiguas salen cuando superan los 4.000 caracteres).

#Registro de sincronización

Cada webhook recibido, persona sincronizada, envío al CRM, prueba y sincronización completa se convierte en una entrada del registro, en Integraciones › CRM (en la conexión) y en GET /crm-connections/{id}/logs. Una entrada tiene:

Los mensajes del registro están escritos en portugués de Brasil.

{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "object": "crm_sync_log",
      "id": "019a2c10-5e6f-7a81-9b2c-3d4e5f6a7b8c",
      "direction": "outbound",
      "object_type": "person",
      "event": "contact.updated",
      "external_id": "51",
      "contact_id": "019a1e00-1a2b-7c3d-8e4f-5a6b7c8d9e0f",
      "action": null,
      "status": "failed",
      "error": "HubSpot recusou as credenciais ou a permissão (HTTP 403). Confira o token e as permissões dele.",
      "attempts": 6,
      "retryable": true,
      "payload": {
        "id": "019a1e00-1a2b-7c3d-8e4f-5a6b7c8d9e0f",
        "email": "[email protected]",
        "first_name": "Ana"
      },
      "next_attempt_at": null,
      "created_at": "2026-10-26T14:05:10.000000Z",
      "updated_at": "2026-10-26T14:05:11.000000Z"
    }
  ]
}

Nuevos intentos

• Los envíos al CRM que fallan se reintentan solos, tras 30 segundos, 2 minutos, 10 minutos, 30 minutos y 2 horas (6 intentos en total). Agotados los intentos, la entrada pasa a failed y la conexión muestra el aviso error (last_error); sigue funcionando y vuelve a active con el primer envío que salga bien. Si el CRM respondió 429, Postal espera al menos lo que pidió.
• Los webhooks recibidos se responden al instante con 202 y se procesan en segundo plano. Si no se pudo consultar el CRM (límite de solicitudes, fuera de servicio), Postal lo intenta de nuevo, hasta 3 veces.
• Una entrada failed con el payload completo se reenvía a mano, en el panel o con POST /crm-connections/{id}/logs/{log_id}/retry, después de corregir la causa (un correo electrónico que faltaba, una propiedad que no existía, el token).

#Por la API

Todo lo que hace el panel está en la API, con una clave de acceso total (una clave solo de envío recibe 401 restricted_api_key). Los IDs son UUID, y las listas siguen la paginación por cursor.

curl -X POST https://api.postal.so/crm-connections/019a2b3c-4d5e-7f60-8a9b-0c1d2e3f4a5b/test \
  -H "Authorization: Bearer $POSTAL_API_KEY"

const response = await fetch('https://api.postal.so/crm-connections/019a2b3c-4d5e-7f60-8a9b-0c1d2e3f4a5b/test', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.POSTAL_API_KEY}`,
  },
});

const data = await response.json();

import os
import requests

response = requests.post(
    "https://api.postal.so/crm-connections/019a2b3c-4d5e-7f60-8a9b-0c1d2e3f4a5b/test",
    headers={"Authorization": f"Bearer {os.environ['POSTAL_API_KEY']}"},
    timeout=10,
)

data = response.json()

$client = new \GuzzleHttp\Client(['base_uri' => 'https://api.postal.so']);

$response = $client->post('crm-connections/019a2b3c-4d5e-7f60-8a9b-0c1d2e3f4a5b/test', [
    'headers' => ['Authorization' => 'Bearer '.getenv('POSTAL_API_KEY')],
]);

$data = json_decode($response->getBody(), true);

{
  "object": "crm_connection_test",
  "ok": true,
  "message": "Connected to HubSpot (12 contacts).",
  "status_code": 200
}

Cuando el CRM rechaza la llamada, ok es false y message trae el motivo. fields, stages y la sincronización que no logran comunicarse con el CRM responden 502 crm_request_failed con el mensaje legible.

curl -X POST https://api.postal.so/crm-connections/019a2b3c-4d5e-7f60-8a9b-0c1d2e3f4a5b/sync \
  -H "Authorization: Bearer $POSTAL_API_KEY"

const response = await fetch('https://api.postal.so/crm-connections/019a2b3c-4d5e-7f60-8a9b-0c1d2e3f4a5b/sync', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.POSTAL_API_KEY}`,
  },
});

const data = await response.json();

import os
import requests

response = requests.post(
    "https://api.postal.so/crm-connections/019a2b3c-4d5e-7f60-8a9b-0c1d2e3f4a5b/sync",
    headers={"Authorization": f"Bearer {os.environ['POSTAL_API_KEY']}"},
    timeout=10,
)

data = response.json()

$client = new \GuzzleHttp\Client(['base_uri' => 'https://api.postal.so']);

$response = $client->post('crm-connections/019a2b3c-4d5e-7f60-8a9b-0c1d2e3f4a5b/sync', [
    'headers' => ['Authorization' => 'Bearer '.getenv('POSTAL_API_KEY')],
]);

$data = json_decode($response->getBody(), true);

{
  "object": "crm_connection",
  "id": "019a2b3c-4d5e-7f60-8a9b-0c1d2e3f4a5b",
  "sync": "queued"
}

curl 'https://api.postal.so/crm-connections/019a2b3c-4d5e-7f60-8a9b-0c1d2e3f4a5b/logs?status=failed' \
  -H "Authorization: Bearer $POSTAL_API_KEY"

const response = await fetch('https://api.postal.so/crm-connections/019a2b3c-4d5e-7f60-8a9b-0c1d2e3f4a5b/logs?status=failed', {
  headers: {
    Authorization: `Bearer ${process.env.POSTAL_API_KEY}`,
  },
});

const data = await response.json();

import os
import requests

response = requests.get(
    "https://api.postal.so/crm-connections/019a2b3c-4d5e-7f60-8a9b-0c1d2e3f4a5b/logs",
    headers={"Authorization": f"Bearer {os.environ['POSTAL_API_KEY']}"},
    params={
        "status": "failed",
    },
    timeout=10,
)

data = response.json()

$client = new \GuzzleHttp\Client(['base_uri' => 'https://api.postal.so']);

$response = $client->get('crm-connections/019a2b3c-4d5e-7f60-8a9b-0c1d2e3f4a5b/logs', [
    'headers' => ['Authorization' => 'Bearer '.getenv('POSTAL_API_KEY')],
    'query' => [
        'status' => 'failed',
    ],
]);

$data = json_decode($response->getBody(), true);

#Límites

#Errores

El formato de los errores y los demás nombres están en Errores.

#Ver también

• Conexión por webhook: para cualquier otro CRM o sistema.
• Integra tu app: Stripe, Supabase, Clerk, Auth0 y Firebase, que usan las mismas conexiones.
• Webhooks: los eventos y la firma que la conexión reutiliza, y el origen de los cambios.
• Contactos, propiedades y automatizaciones.
• Servidor MCP: un asistente de IA también puede consultar y ajustar los contactos que el CRM sincroniza.