Contactos

Gestiona los contactos en Contactos > Todos los contactos en el panel de control, con bird contacts desde el terminal, mediante la API de contactos o con cualquiera de los SDK.

Contactar con tus contactos

Para enviar un correo a una persona, usa su dirección con la API de envío; el registro del contacto conserva su información para que puedas reutilizarla. Para dirigirte a muchas personas a la vez, envía un lote o agrúpalas en una audiencia y envía una difusión. Almacenar un contacto no envía nada por sí solo.

La página Contactos

La página Contactos muestra el nombre del contacto, sus identificadores, las audiencias a las que pertenece y la información de creación. Busca por nombre, correo electrónico o teléfono y selecciona una fila para abrir el contacto. Usa las acciones de la cabecera para añadir un contacto o importar varios. Para verlos necesitas permiso de lectura de email_marketing. Para añadirlos, editarlos o eliminarlos necesitas permiso de escritura.

Qué contiene un contacto

Cada contacto tiene una dirección de correo electrónico, un número de teléfono o ambos, cada uno único en tu espacio de trabajo, además de un nombre y un identificador propio opcionales:

Campo	Qué es
email	La dirección, única en tu espacio de trabajo. La almacenamos sin espacios al principio ni al final y en minúsculas, por lo que Sam@Acme.com y sam@acme.com se normalizan al mismo identificador.
phone_number	El número de teléfono, único en tu espacio de trabajo. Su formato se normaliza al formato internacional. Almacenarlo no verifica los metadatos del plan de numeración, la titularidad, la posibilidad de contactar con el número ni el consentimiento.
first_name	Nombre de pila opcional, usado para personalizar un envío.
last_name	Apellido opcional.
external_id	Opcional. Tu propia clave primaria para la persona (un ID de usuario de tu base de datos), única en tu espacio de trabajo cuando se establece. Te permite vincular un contacto con tus propios registros sin depender del correo electrónico.
data	Valores de propiedades personalizadas, uno por cada propiedad de contacto registrada.

El panel de control genera las etiquetas Email y SMS a partir de los identificadores presentes. La API devuelve email y phone_number; no devuelve un campo channels. Esas etiquetas no acreditan el permiso de envío ni la posibilidad de contactar por ese canal.

Cada contacto también tiene un ID con el prefijo con_ y marcas de tiempo de creación y actualización. La referencia de la API incluye la especificación completa de los campos.

Propiedades de contacto

Las propiedades de contacto definen el esquema tipado de los campos personalizados de un contacto. Registra una propiedad para tu espacio de trabajo y, a partir de entonces, cada contacto podrá tener un valor para ella en data. Declarar el esquema de antemano hace que la personalización y la segmentación sean fiables: cada valor siempre llega con el tipo que declaraste, de modo que una plantilla o un filtro puede contar con él.

Gestiónalas en Contactos > Propiedades de contacto. Cada propiedad tiene una clave, un tipo y un valor predeterminado opcional:

La clave es el nombre con el que haces referencia al valor, por ejemplo, plan_tier. Debe estar en minúsculas y comenzar por una letra (^[a-z][a-z0-9_]*$), y no se puede cambiar después de crearla.
El tipo es uno de los siguientes: string, number, boolean o datetime, y tampoco se puede cambiar después de crear la propiedad. Un datetime acepta una marca de tiempo RFC 3339 con un desfase explícito, como 2026-01-15T11:30:00+02:00, que normalizamos a UTC con precisión de segundos. Por tanto, ese valor se almacena y se devuelve como 2026-01-15T09:30:00Z. Se rechaza una fecha sin hora. En el panel de control, estos tipos aparecen como Texto, Número, Verdadero / falso y Fecha y hora.
El valor predeterminado es el que se obtiene al leer la propiedad de un contacto que no tiene un valor propio. Así, si falta plan_tier, puede devolverse free en lugar de un valor vacío.

Las propiedades se archivan en lugar de eliminarse. Archivarlas impide nuevas escrituras en la clave, pero conserva todos los valores ya almacenados. La clave permanece reservada, por lo que nunca podrá reutilizarse con otro tipo. Desarchiva la propiedad para volver a usarla. Esa reserva también explica por qué el tipo es inmutable: un number almacenado nunca debe empezar a leerse como un string. Un espacio de trabajo puede registrar hasta 200 propiedades, y las archivadas cuentan para ese límite porque sus claves siguen reservadas.

Establece los valores de las propiedades donde edites un contacto. El formulario de contacto del panel de control muestra un campo de entrada tipado por cada propiedad activa, y la CLI y la API aceptan las mismas claves en data.

Importar y sincronizar contactos

Para importar una lista desde la página Contactos, selecciona Importar y sube un archivo CSV, TSV o Excel. Incluye un contacto por fila y una fila de cabecera con los nombres de las columnas. Un archivo puede contener hasta 50.000 contactos. Los archivos CSV pueden ocupar hasta 50 MB y las hojas de cálculo hasta 10 MB.

La fila de cabecera ayuda a identificar cada campo de contacto. Las columnas llamadas "Email Address", "E-Mail" o "Correo electrónico" se asignan todas al campo de correo electrónico. Una columna que contiene el nombre completo se divide en nombre y apellido. Si dos columnas pueden completar el mismo campo, se elige aquella cuyos valores respaldan su nombre. Cada columna muestra algunos de sus valores para que veas qué contiene, y los nombres divididos se muestran junto al valor original. Cambia cualquier asignación desde el desplegable de cada columna. Puedes añadir a todas las personas del archivo a una o más audiencias en esa misma importación.

Cada fila se vincula a un contacto existente mediante sus identificadores y lo actualiza, o crea uno si es nuevo. Por tanto, volver a importar el mismo archivo crea o actualiza los contactos mediante upsert en lugar de acumular duplicados. Antes de escribir nada, el panel de control informa de cuántas filas iniciales no se pueden importar con la asignación actual. Tras la ejecución, cada fila omitida indica su número de línea de origen y el error.

Para sincronizar desde tu propia base de datos, automatiza la CLI con un script o llama al endpoint de procesamiento por lotes. bird contacts create <email> añade un contacto. bird contacts batch crea o actualiza hasta 1.000 en una sola llamada. Usa un lote por ejecución en lugar de una solicitud por persona para mantener tu lista de contactos sincronizada con tu sistema.

const contact = await bird.contacts.create({
  email: "jane@acme.com",
  first_name: "Jane",
});
console.log(contact.id); // "con_…"

contact = client.contacts.create(email="jane@acme.com", first_name="Jane")
print(contact.id, contact.email)

contact, err := client.Contacts.Create(context.Background(), bird.ContactCreateParams{
	Email:     bird.Ptr("jane@acme.com"),
	FirstName: bird.Ptr("Jane"),
})
if err != nil {
	log.Fatal(err)
}
fmt.Println(contact.Id)

$contact = $bird->contacts->create(
    (new ContactCreateRequest())
        ->setEmail('jane@acme.com')
        ->setFirstName('Jane'),
);
echo $contact->getId(); // "con_…"

bird contacts create alice@acme.com \
  --first-name Alice \
  --last-name Anderson \
  --phone-number +31612345678

{
  "name": "contacts_create",
  "arguments": {
    "email": "alice@acme.com",
    "first_name": "Alice",
    "last_name": "Anderson",
    "phone_number": "+31612345678"
  }
}

curl -X POST "https://{region}.platform.bird.com/v1/contacts" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "alice@acme.com",
    "phone_number": "+31612345678",
    "first_name": "Alice",
    "last_name": "Anderson"
  }'

Cada entrada del lote se vincula automáticamente mediante los identificadores que proporciona (dirección de correo electrónico, número de teléfono o ID externo). El campo opcional match_on obliga a usar solo uno de ellos para buscar coincidencias. Una entrada también puede establecer valores de propiedades personalizadas y añadir directamente todos los contactos de la solicitud a audiencias mediante audience_ids. Cada entrada se procesa correctamente o falla de forma independiente, y la respuesta indica un resultado por entrada en el orden de envío:

Ejemplo de código

{
  "data": [
    {
      "contact_id": "con_01ky7q5t51echr7mqj5c08423b",
      "entry": { "email": "alex@example.com", "phone_number": null, "external_id": null },
      "matched_on": "email",
      "status": "updated"
    },
    {
      "contact_id": "con_01ky7q6mxdfhe86c9dqyt866pz",
      "entry": { "email": "jamie@example.com", "phone_number": null, "external_id": null },
      "matched_on": null,
      "status": "created"
    },
    {
      "contact_id": "con_01ky7q7rv9e9pt4vkr0w0gxq5e",
      "entry": { "email": "casey@example.com", "phone_number": null, "external_id": "user_2214" },
      "matched_on": "external_id",
      "status": "updated"
    }
  ]
}

Si los identificadores de una entrada apuntan a distintos contactos existentes, la entrada falla con un conflicto que debes revisar. Resuelve el registro de origen antes de reintentar; el lote no fusiona esos contactos.

Dos comportamientos predeterminados son útiles para una sincronización. Un lote combina las claves data con los datos existentes del contacto, de modo que una importación que modifica un atributo nunca borra los demás. Envía un valor null para borrar una clave, o establece data_mode: "replace" para sobrescribir todo el mapa. Establece tu propio external_id en cada contacto para que una sincronización posterior encuentre a la misma persona aunque cambie su correo electrónico. En el ejemplo del lote, user_2214 ya existe, por lo que la entrada se vincula a ese contacto y sustituye su dirección de correo por la nueva.

Eliminar un contacto

Eliminar un contacto es permanente: desaparecen el registro y su pertenencia a las audiencias, y no se pueden recuperar. Sin embargo, las supresiones y las preferencias no cambian. Una dirección que ha generado un rebote duro permanece en tu lista de supresión, y una que ha cancelado la suscripción conserva su preferencia de no recibir mensajes después de eliminar el contacto. Por tanto, eliminar a alguien nunca vuelve a habilitar silenciosamente el envío a su dirección.

Siguientes pasos

Audiencias: agrupa contactos en listas reutilizables
Supresiones: la lista del espacio de trabajo con las direcciones a las que no entregamos mensajes, independiente de tus contactos
Envíos por lotes: dirígete a muchos destinatarios en una sola llamada, con hasta 100 mensajes por solicitud
CLI: automatiza contactos, propiedades y audiencias con el comando bird
Referencia de la API: los esquemas completos de solicitudes y respuestas

Recursos relacionados

Continúa con la documentación, guías y ejemplos sobre este tema. Los recursos están en inglés.

Ver la guíaGetting started with email Explorar la funcionalidadEmail Seguir la ruta de aprendizajeBuild your first integration Guía de implementaciónSend your first email

Prueba el ejercicio y obtén un resumen de implementación