Suscriptores
Añade, actualiza y quita los suscriptores de una lista de contactos.
Añadir un suscriptor
Añade un contacto a una lista de contactos a partir de su dirección de email.
/audiences/{audience_id}/subscribersRequiere una clave de API full. Si todavía no hay ningún contacto con este email, Emailit lo crea. Si el contacto existe, el nombre, los apellidos y los campos personalizados que envíes sobrescriben sus valores actuales. Un contacto que se había dado de baja de la lista se vuelve a suscribir y la respuesta es 200; un contacto que ya está suscrito devuelve 409.
Cada lista admite tantos suscriptores como permita tu plan; por encima de ese número, la petición devuelve 422 con tu usage. Dispara subscriber.created o, si el contacto se vuelve a suscribir, subscriber.updated y subscriber.resubscribed.
Parámetros de ruta
audience_idstringobligatorioaud_…) o su nombre.Parámetros del cuerpo
emailstringobligatoriofirst_namestringlast_namestringcustom_fieldsobjectLos valores de los campos personalizados por clave, como {"company": "Analytical Engines"}. Sustituye los campos personalizados que ya tenga el contacto.
Devuelve
Devuelve 201 con el objeto de suscriptor, o 200 si se ha vuelto a suscribir un contacto dado de baja.
{
"object": "subscriber",
"id": "sub_4KECYl5AwXEy8ezswYRhuddttxo",
"audience_id": "aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2",
"contact_id": "con_4K9kQdrXth7am0TPKvPrR5yd2oo",
"email": "ada@example.com",
"first_name": "Ada",
"last_name": "Lovelace",
"custom_fields": {
"company": "Analytical Engines"
},
"subscribed": true,
"subscribed_at": "2026-10-01T10:20:31.000000Z",
"unsubscribed_at": null,
"created_at": "2026-10-01T10:20:31.000000Z",
"updated_at": "2026-10-01T10:20:31.000000Z"
}{
"error": "Audience not found"
}{
"error": "Contact is already subscribed to this audience",
"existing": {
"object": "subscriber",
"id": "sub_4KECYl5AwXEy8ezswYRhuddttxo",
"audience_id": "aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2",
"contact_id": "con_4K9kQdrXth7am0TPKvPrR5yd2oo",
"email": "ada@example.com",
"first_name": "Ada",
"last_name": "Lovelace",
"custom_fields": { "company": "Analytical Engines" },
"subscribed": true,
"subscribed_at": "2026-10-01T10:20:31.000Z",
"unsubscribed_at": null,
"created_at": "2026-10-01T10:20:31.000Z",
"updated_at": "2026-10-01T10:20:31.000Z"
}
}{
"error": "Pro includes 50,000 subscribers per audience.",
"usage": {
"used": 50000,
"limit": 50000,
"plan": "pro"
}
}Obtener un suscriptor
Obtiene la pertenencia de un contacto a una lista de contactos.
/audiences/{audience_id}/subscribers/{id}Requiere una clave de API full. Un suscriptor vincula un contacto a una lista. El email, el nombre, los apellidos y los campos personalizados pertenecen al contacto; subscribed pertenece solo a esta lista.
Parámetros de ruta
audience_idstringobligatorioaud_…) o su nombre.idstringobligatoriosub_…) o la dirección de email del contacto, codificada para URL.Devuelve
Devuelve el objeto de suscriptor.
objectstringsubscriber.idstringaudience_idstringcontact_idstringemailstringfirst_namestring | nulllast_namestring | nullcustom_fieldsobject | nullsubscribedbooleantrue si el contacto está suscrito a esta lista, false si se ha dado de baja.subscribed_atstring | nullunsubscribed_atstring | nullnull.created_atstringupdated_atstring{
"object": "subscriber",
"id": "sub_4KECYl5AwXEy8ezswYRhuddttxo",
"audience_id": "aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2",
"contact_id": "con_4K9kQdrXth7am0TPKvPrR5yd2oo",
"email": "ada@example.com",
"first_name": "Ada",
"last_name": "Lovelace",
"custom_fields": {
"company": "Analytical Engines"
},
"subscribed": true,
"subscribed_at": "2026-10-01T10:20:31.000000Z",
"unsubscribed_at": null,
"created_at": "2026-10-01T10:20:31.000000Z",
"updated_at": "2026-10-01T10:20:31.000000Z"
}{
"error": "Subscriber not found"
}Actualizar un suscriptor
Cambia el estado de un suscriptor en la lista o los datos de su contacto.
/audiences/{audience_id}/subscribers/{id}Requiere una clave de API full. Envía solo los campos que quieras cambiar. subscribed se aplica solo a esta lista. email, first_name, last_name y custom_fields modifican el propio contacto, así que el cambio aparece en todas las listas a las que pertenece. Dispara un evento subscriber.updated.
Parámetros de ruta
audience_idstringobligatorioaud_…) o su nombre.idstringobligatoriosub_…) o la dirección de email del contacto, codificada para URL.Parámetros del cuerpo
subscribedbooleanfalse para dar de baja al contacto de esta lista, true para volver a suscribirlo. En ambos casos, el suscriptor sigue en la lista.emailstringfirst_namestringlast_namestringcustom_fieldsobjectDevuelve
Devuelve el objeto de suscriptor actualizado. Una petición sin ninguno de estos campos devuelve 400.
curl -X POST https://api.emailit.com/v2/audiences/aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2/subscribers/ada%40example.com \
-H "Authorization: Bearer $EMAILIT_API_KEY" \
-H "Content-Type: application/json" \
-d '{"subscribed": false}'{
"object": "subscriber",
"id": "sub_4KECYl5AwXEy8ezswYRhuddttxo",
"audience_id": "aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2",
"contact_id": "con_4K9kQdrXth7am0TPKvPrR5yd2oo",
"email": "ada@example.com",
"first_name": "Ada",
"last_name": "Lovelace",
"custom_fields": {
"company": "Analytical Engines"
},
"subscribed": false,
"subscribed_at": "2026-10-01T10:20:31.000000Z",
"unsubscribed_at": "2026-10-02T08:14:55.000000Z",
"created_at": "2026-10-01T10:20:31.000000Z",
"updated_at": "2026-10-02T08:14:55.000000Z"
}{
"error": "No valid fields provided for update. Provide at least one of: email, first_name, last_name, custom_fields, subscribed"
}{
"error": "Subscriber not found"
}Listar suscriptores
Devuelve una página de suscriptores de una lista de contactos, del más reciente al más antiguo.
/audiences/{audience_id}/subscribersRequiere una clave de API full. El listado incluye los contactos que se han dado de baja de la lista, salvo que los excluyas con subscribed=true.
Parámetros de ruta
audience_idstringobligatorioaud_…) o su nombre.Parámetros de consulta
pageintegerpor defecto: 1limitintegerpor defecto: 25per_page.subscribedstringtrue para obtener solo los contactos suscritos; false, solo los dados de baja.searchstringmatchstringpor defecto: allall u or. Cómo se combinan los filtros de abajo.orderstringdirectionstringasc o desc.Filtros
Añade filtros con el formato key.condition=value, por ejemplo email.ends_with=@acme.com. Consulta Filtrado.
| Clave | Tipo | Notas |
|---|---|---|
email |
cadena | |
first_name |
cadena | |
last_name |
cadena | |
subscribed |
booleano | |
created_at |
fecha | Cuándo se unió el contacto a la lista. |
Todas las claves sirven también para ordenar.
Devuelve
dataobject[]next_page_urlstring | nullnull. Conserva subscribed, pero no el resto de tus filtros. Consulta Paginación.previous_page_urlstring | nullnull.usageobjectused (los suscriptores de la lista), limit (el máximo que permite tu plan por lista, o null) y plan.curl -G https://api.emailit.com/v2/audiences/aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2/subscribers \
-H "Authorization: Bearer $EMAILIT_API_KEY" \
-d subscribed=true \
-d limit=100{
"data": [
{
"object": "subscriber",
"id": "sub_4KECYl5AwXEy8ezswYRhuddttxo",
"audience_id": "aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2",
"contact_id": "con_4K9kQdrXth7am0TPKvPrR5yd2oo",
"email": "ada@example.com",
"first_name": "Ada",
"last_name": "Lovelace",
"custom_fields": {
"company": "Analytical Engines"
},
"subscribed": true,
"subscribed_at": "2026-10-01T10:20:31.000000Z",
"unsubscribed_at": null,
"created_at": "2026-10-01T10:20:31.000000Z",
"updated_at": "2026-10-01T10:20:31.000000Z"
},
{
"object": "subscriber",
"id": "sub_4KnmYprkoMRytdkm3tAHIfPW0Vh",
"audience_id": "aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2",
"contact_id": "con_4KiXIs4xLTcJIAHnKJaLcnMZYh7",
"email": "grace@example.com",
"first_name": "Grace",
"last_name": "Hopper",
"custom_fields": null,
"subscribed": false,
"subscribed_at": "2026-09-28T07:55:02.000000Z",
"unsubscribed_at": "2026-09-30T18:11:40.000000Z",
"created_at": "2026-09-28T07:55:02.000000Z",
"updated_at": "2026-09-30T18:11:40.000000Z"
}
],
"next_page_url": null,
"previous_page_url": null,
"usage": {
"used": 2,
"limit": 50000,
"plan": "pro"
}
}{
"error": "Audience not found"
}Eliminar un suscriptor
Quita un contacto de una lista de contactos.
/audiences/{audience_id}/subscribers/{id}Requiere una clave de API full. El contacto no se elimina y sigue en sus otras listas. Para dejar constancia de que alguien se dio de baja, da de baja al suscriptor con subscribed: false en lugar de eliminarlo. Dispara un evento subscriber.deleted.
Parámetros de ruta
audience_idstringobligatorioaud_…) o su nombre.idstringobligatoriosub_…) o la dirección de email del contacto, codificada para URL.Devuelve
objectstringsubscriber.idstringaudience_idstringcontact_idstringemailstringdeletedbooleantrue.{
"object": "subscriber",
"id": "sub_4KECYl5AwXEy8ezswYRhuddttxo",
"audience_id": "aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2",
"contact_id": "con_4K9kQdrXth7am0TPKvPrR5yd2oo",
"email": "ada@example.com",
"deleted": true
}{
"error": "Subscriber not found"
}