Saltar al contenido
Docs

Añade, actualiza y quita los suscriptores de una lista de contactos.

URL basehttps://api.emailit.com/v2AutenticaciónErroresLímites de velocidad

Añadir un suscriptor

Añade un contacto a una lista de contactos a partir de su dirección de email.

POST/audiences/{audience_id}/subscribers

Requiere 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_idstringobligatorio
El ID de la lista (aud_…) o su nombre.

Parámetros del cuerpo

emailstringobligatorio
La dirección de email que se suscribe. Se guarda en minúsculas.
first_namestring
El nombre del contacto.
last_namestring
Los apellidos del contacto.
custom_fieldsobject

Los 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.

POST/audiences/{audience_id}/subscribers
Terminal
curl -X POST https://api.emailit.com/v2/audiences/aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2/subscribers \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "ada@example.com",
    "first_name": "Ada",
    "last_name": "Lovelace",
    "custom_fields": { "company": "Analytical Engines" }
  }'
JSON
{
  "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"
}

Obtener un suscriptor

Obtiene la pertenencia de un contacto a una lista de contactos.

GET/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_idstringobligatorio
El ID de la lista (aud_…) o su nombre.
idstringobligatorio
El ID del suscriptor (sub_…) o la dirección de email del contacto, codificada para URL.

Devuelve

Devuelve el objeto de suscriptor.

objectstring
Siempre subscriber.
idstring
El ID del suscriptor.
audience_idstring
El ID de la lista.
contact_idstring
El ID del contacto.
emailstring
La dirección de email del contacto.
first_namestring | null
El nombre del contacto.
last_namestring | null
Los apellidos del contacto.
custom_fieldsobject | null
Los valores de los campos personalizados del contacto.
subscribedboolean
true si el contacto está suscrito a esta lista, false si se ha dado de baja.
subscribed_atstring | null
Cuándo se suscribió el contacto por última vez.
unsubscribed_atstring | null
Cuándo se dio de baja el contacto, o null.
created_atstring
Cuándo se unió el contacto a la lista.
updated_atstring
Cuándo cambió la pertenencia por última vez.
GET/audiences/{audience_id}/subscribers/{id}
Terminal
curl https://api.emailit.com/v2/audiences/aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2/subscribers/sub_4KECYl5AwXEy8ezswYRhuddttxo \
  -H "Authorization: Bearer $EMAILIT_API_KEY"
JSON
{
  "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"
}

Actualizar un suscriptor

Cambia el estado de un suscriptor en la lista o los datos de su contacto.

POST/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_idstringobligatorio
El ID de la lista (aud_…) o su nombre.
idstringobligatorio
El ID del suscriptor (sub_…) o la dirección de email del contacto, codificada para URL.

Parámetros del cuerpo

subscribedboolean
false para dar de baja al contacto de esta lista, true para volver a suscribirlo. En ambos casos, el suscriptor sigue en la lista.
emailstring
Una nueva dirección de email para el contacto. Se guarda en minúsculas.
first_namestring
El nombre del contacto.
last_namestring
Los apellidos del contacto.
custom_fieldsobject
Los valores de los campos personalizados por clave. Sustituye los campos personalizados que ya tenga el contacto.

Devuelve

Devuelve el objeto de suscriptor actualizado. Una petición sin ninguno de estos campos devuelve 400.

POST/audiences/{audience_id}/subscribers/{id}
Terminal
curl -X POST https://api.emailit.com/v2/audiences/aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2/subscribers/sub_4KECYl5AwXEy8ezswYRhuddttxo \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"first_name": "Augusta"}'
Terminal
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}'
JSON
{
  "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"
}

Listar suscriptores

Devuelve una página de suscriptores de una lista de contactos, del más reciente al más antiguo.

GET/audiences/{audience_id}/subscribers

Requiere 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_idstringobligatorio
El ID de la lista (aud_…) o su nombre.

Parámetros de consulta

pageintegerpor defecto: 1
La página que se devuelve.
limitintegerpor defecto: 25
Suscriptores por página, de 1 a 100. También funciona per_page.
subscribedstring
true para obtener solo los contactos suscritos; false, solo los dados de baja.
matchstringpor defecto: all
all u or. Cómo se combinan los filtros de abajo.
orderstring
Una clave de filtro por la que ordenar.
directionstring
asc 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[]
Los objetos de suscriptor de esta página.
next_page_urlstring | null
La ruta de la página siguiente, o null. Conserva subscribed, pero no el resto de tus filtros. Consulta Paginación.
previous_page_urlstring | null
La ruta de la página anterior, o null.
usageobject
used (los suscriptores de la lista), limit (el máximo que permite tu plan por lista, o null) y plan.
GET/audiences/{audience_id}/subscribers
Terminal
curl https://api.emailit.com/v2/audiences/aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2/subscribers \
  -H "Authorization: Bearer $EMAILIT_API_KEY"
Terminal
curl -G https://api.emailit.com/v2/audiences/aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2/subscribers \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -d subscribed=true \
  -d limit=100
JSON
{
  "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"
  }
}

Eliminar un suscriptor

Quita un contacto de una lista de contactos.

DELETE/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_idstringobligatorio
El ID de la lista (aud_…) o su nombre.
idstringobligatorio
El ID del suscriptor (sub_…) o la dirección de email del contacto, codificada para URL.

Devuelve

objectstring
Siempre subscriber.
idstring
El ID del suscriptor eliminado.
audience_idstring
El ID de la lista.
contact_idstring
El ID del contacto.
emailstring
La dirección de email del contacto.
deletedboolean
Siempre true.
DELETE/audiences/{audience_id}/subscribers/{id}
Terminal
curl -X DELETE https://api.emailit.com/v2/audiences/aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2/subscribers/sub_4KECYl5AwXEy8ezswYRhuddttxo \
  -H "Authorization: Bearer $EMAILIT_API_KEY"
JSON
{
  "object": "subscriber",
  "id": "sub_4KECYl5AwXEy8ezswYRhuddttxo",
  "audience_id": "aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2",
  "contact_id": "con_4K9kQdrXth7am0TPKvPrR5yd2oo",
  "email": "ada@example.com",
  "deleted": true
}

¿Te ha resultado útil esta página?

Gracias por tu opinión.

Gracias. Leemos todos los mensajes.