Contactos
Las personas a las que envías email de marketing, con su estado de suscripción y sus propiedades personalizadas.
Un contacto es una dirección de email de la lista de tu equipo. Cada dirección aparece una sola vez (no distingue mayúsculas de minúsculas), y eliges quién recibe un envío masivo con segmentos y temas. Gestiona los contactos en el panel, en Contactos, o con la API.
Qué guarda un contacto
email: la dirección. Crear un segundo contacto con la misma dirección devuelve409. Una dirección que nunca podrá recibir correo (por ejemploexample.com, un nombre.testo un dominio sin servidor de correo) devuelve422.first_name,last_name.unsubscribed: la baja de todo tu equipo. Mientras valgatrue, el contacto no recibe email de marketing de ninguno de tus dominios. Solo la configuras tú; la baja que hace el propio destinatario nunca la cambia.unsubscribed_domains: solo lectura. Los dominios de los que el contacto se dio de baja con un enlace de baja, cada uno condomain_id,nameyunsubscribed_at. El correo de esos dominios omite al contacto, y tus otros dominios siguen llegándole. Consulta Bajas.verification_statusyverified_at: solo lectura. El resultado de la última verificación profunda del contacto,nullhasta que se verifica. Consulta Verificación.properties: valores personalizados comoplan: "pro"ocity: "Berlin". Los valores son cadenas o números (los objetos o arrays anidados devuelven422), con un máximo de 100 claves por contacto. Las propiedades rellenan los campos de combinación de las plantillas y los filtros de los segmentos.PATCHlas combina clave por clave, y un valornullelimina la clave.
Crear y leer
POST /contacts, GET /contacts, GET /contacts/{id}, PATCH /contacts/{id} y DELETE /contacts/{id}. En {id} puedes usar el id del contacto o su dirección de email.
curl -X POST "https://api.billionsend.com/contacts" \
-H "Authorization: Bearer bs_..." \
-H "Content-Type: application/json" \
-d '{
"email": "ana@acme.com",
"first_name": "Ana",
"properties": { "plan": "pro" }
}'
Añade include=properties,topics a GET /contacts o a GET /segments/{id}/contacts para recibir las propiedades y las opciones de temas de cada contacto en la misma respuesta. POST /contacts/batch/get lee hasta 1000 contactos por id o email en una sola llamada, en el orden de la solicitud; las direcciones que no coinciden con nada se listan en missing.
PATCH /contacts/{id}/topics define las opciones de temas de un contacto, y GET /contacts/{id}/topics las lee de vuelta con los valores por defecto de los temas aplicados.
POST /contacts/{id}/preferences-link devuelve un enlace a la página de preferencias del contacto, para que puedas abrirla desde una pantalla de ajustes de tu producto. El enlace no caduca y permite a quien lo tenga cambiar las opciones de ese contacto, así que entrégalo solo al propio contacto. Abre la página por defecto del equipo y da de baja al contacto de todos los dominios.
Creación en lote
POST /contacts/batch acepta de 1 a 1000 contactos en una sola solicitud y los escribe juntos.
on_conflict indica qué pasa cuando una dirección ya existe o se repite en el lote:
error(por defecto): ese elemento falla con409(ya existe) o422(repetido).skip: el contacto existente se deja como está.upsert: el elemento se combina con el contacto existente. Los nombres solo si los envías, las propiedades clave por clave, se añaden los segmentos y se actualizan los temas.
Un lote nunca vuelve a suscribir a nadie: unsubscribed: false en un contacto que ya está dado de baja se ignora. Para eso usa PATCH /contacts/{id}.
La cabecera x-batch-validation elige strict (por defecto: un elemento incorrecto rechaza todo el lote) o permissive (se escriben los elementos válidos y los fallos se listan en errors).
curl -X POST "https://api.billionsend.com/contacts/batch?on_conflict=upsert" \
-H "Authorization: Bearer bs_..." \
-H "Content-Type: application/json" \
-H "x-batch-validation: permissive" \
-d '[{ "email": "ana@acme.com", "properties": { "plan": "pro" } }, { "email": "not-an-address" }]'
{
"data": [{ "object": "contact", "index": 0, "id": "9b2f…", "status": "updated" }],
"counts": { "created": 0, "updated": 1, "skipped": 0, "failed": 1 },
"errors": [{ "index": 1, "statusCode": 422, "name": "validation_error", "message": "email: Invalid email address" }]
}
Eliminación en lote
POST /contacts/batch/remove elimina hasta 1000 contactos por ids o por emails (uno de los dos) y devuelve los que eliminó. Añade erase: true para quitar también cada dirección del historial de emails, de las cargas de los eventos y de los registros de la API. DELETE /contacts/{id}?erase=true hace lo mismo con un solo contacto.
Importar y exportar CSV
En el panel, Contactos importa un CSV y exporta la vista actual (incluido un filtro por segmento, tema o dominio) de vuelta a CSV. La exportación tiene una columna unsubscribed y una columna unsubscribed_domains (* significa todo el equipo). Se omiten las filas con una dirección que nunca podrá recibir correo. En un plan de pago, el diálogo de importación también puede verificar las direcciones nuevas; consulta Verificación.
Eventos
Cada cambio publica un evento de webhook: contact.created, contact.updated, contact.deleted, contact.unsubscribed, contact.resubscribed, contact.topic_opt_in y contact.topic_opt_out.
Límites
| Free | Starter, Pro, Scale | |
|---|---|---|
| Contactos por equipo | 1000 | Sin límite |
Al pasar el límite, crear un contacto devuelve 403 plan_limit_reached. Los contactos existentes se siguen actualizando.