Suscriptores

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

URL basehttps://api.emailit.com/v2Autenticación Errores Límites de velocidad

POST/audiences/{audience_id}/subscribers
GET/audiences/{audience_id}/subscribers/{id}
POST/audiences/{audience_id}/subscribers/{id}
GET/audiences/{audience_id}/subscribers
POST/audiences/{audience_id}/subscribers/bulk
DEL/audiences/{audience_id}/subscribers/{id}

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.

Con double_opt_in, la persona recibe el email de doble opt-in de la lista y se une cuando hace clic en el enlace, así que la respuesta es 202 y todavía no existe ningún suscriptor.

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.

double_opt_inbooleanpor defecto: false

Envía el email de doble opt-in en lugar de suscribir a la persona de inmediato. La lista debe tener activado el doble opt-in; si no, la petición devuelve 422. Una persona que ya está suscrita recibe 409, como siempre.

send_confirmation_emailbooleanpor defecto: false

Envía el email de confirmación de la lista después de suscribir a la persona, si la lista lo tiene activado.

Devuelve

Devuelve 201 con el objeto de suscriptor, o 200 si se ha vuelto a suscribir un contacto dado de baja. Con double_opt_in, devuelve 202 con object: "subscriber_confirmation", status: "pending", audience_id, contact_id y email. Si el email de doble opt-in no se puede enviar, la petición devuelve 422 con un code como unverified_domain o insufficient_credits.

POST/audiences/{audience_id}/subscribers

JavaScript

import { Emailit } from '@emailit/node';
const emailit = new Emailit('your_api_key');

const subscriber = await emailit.subscribers.create('aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2', {
  email: 'ada@example.com',
  first_name: 'Ada',
  last_name: 'Lovelace',
});

Python

from emailit import EmailitClient
client = EmailitClient("your_api_key")

subscriber = client.subscribers.create("aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2", {
  "email": "ada@example.com",
  "first_name": "Ada",
  "last_name": "Lovelace",
})

PHP

$emailit = Emailit::client('your_api_key');

$subscriber = $emailit->subscribers()->create('aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2', [
  'email' => 'ada@example.com',
  'first_name' => 'Ada',
  'last_name' => 'Lovelace',
]);

Ruby

require "emailit"
client = Emailit::EmailitClient.new("your_api_key")

subscriber = client.subscribers.create("aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2",
  email: "ada@example.com",
  first_name: "Ada",
  last_name: "Lovelace"
)

import "github.com/emailit/emailit-go/v2"
client := emailit.NewClient("your_api_key")

subscriber, err := client.Subscribers.Create("aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2", &emailit.CreateSubscriberRequest{
  Email:     "ada@example.com",
  FirstName: "Ada",
  LastName:  "Lovelace",
})

Rust

use emailit::Emailit;
use emailit::types::CreateSubscriberParams;

let emailit = Emailit::new("your_api_key");

let subscriber = emailit.subscribers.create("aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2",
  CreateSubscriberParams::new("ada@example.com")
    .with_first_name("Ada")
    .with_last_name("Lovelace")
).await?;

Java

import com.emailit.*;
import com.emailit.params.*;

EmailitClient emailit = new EmailitClient("your_api_key");

EmailitObject subscriber = emailit.subscribers().create("aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2",
  SubscriberCreateParams.builder()
    .setEmail("ada@example.com")
    .setFirstName("Ada")
    .setLastName("Lovelace")
    .build()
);

using Emailit;

var emailit = new EmailitClient("your_api_key");

var subscriber = emailit.Subscribers.Create("aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2", new SubscriberCreateOptions {
  Email = "ada@example.com",
  FirstName = "Ada",
  LastName = "Lovelace",
});

PHP

use Emailit\Laravel\Facades\Emailit;

$subscriber = Emailit::subscribers()->create('aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2', [
  'email' => 'ada@example.com',
  'first_name' => 'Ada',
  'last_name' => 'Lovelace',
]);

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"
}

JSON

{
  "object": "subscriber_confirmation",
  "status": "pending",
  "audience_id": "aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2",
  "contact_id": "con_4K9kQdrXth7am0TPKvPrR5yd2oo",
  "email": "ada@example.com",
  "message": "A double opt-in email was sent. They join the audience when they click its link."
}

JSON

{
  "error": "Audience not found"
}

JSON

{
  "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"
  }
}

JSON

{
  "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.

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}

JavaScript

import { Emailit } from '@emailit/node';
const emailit = new Emailit('your_api_key');

const subscriber = await emailit.subscribers.get('aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2', 'sub_4KECYl5AwXEy8ezswYRhuddttxo');

Python

from emailit import EmailitClient
client = EmailitClient("your_api_key")

subscriber = client.subscribers.get("aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2", "sub_4KECYl5AwXEy8ezswYRhuddttxo")

PHP

$emailit = Emailit::client('your_api_key');

$subscriber = $emailit->subscribers()->get('aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2', 'sub_4KECYl5AwXEy8ezswYRhuddttxo');

Ruby

require "emailit"
client = Emailit::EmailitClient.new("your_api_key")

subscriber = client.subscribers.get("aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2", "sub_4KECYl5AwXEy8ezswYRhuddttxo")

import "github.com/emailit/emailit-go/v2"
client := emailit.NewClient("your_api_key")

subscriber, err := client.Subscribers.Get("aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2", "sub_4KECYl5AwXEy8ezswYRhuddttxo")

Rust

use emailit::Emailit;

let emailit = Emailit::new("your_api_key");

let subscriber = emailit.subscribers.get("aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2", "sub_4KECYl5AwXEy8ezswYRhuddttxo").await?;

Java

import com.emailit.*;

EmailitClient emailit = new EmailitClient("your_api_key");

EmailitObject subscriber = emailit.subscribers().get("aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2", "sub_4KECYl5AwXEy8ezswYRhuddttxo");

using Emailit;

var emailit = new EmailitClient("your_api_key");

var subscriber = emailit.Subscribers.Get("aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2", "sub_4KECYl5AwXEy8ezswYRhuddttxo");

PHP

use Emailit\Laravel\Facades\Emailit;

$subscriber = Emailit::subscribers()->get('aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2', 'sub_4KECYl5AwXEy8ezswYRhuddttxo');

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"
}

JSON

{
  "error": "Subscriber not found"
}

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}

JavaScript

import { Emailit } from '@emailit/node';
const emailit = new Emailit('your_api_key');

const subscriber = await emailit.subscribers.update('aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2', 'sub_4KECYl5AwXEy8ezswYRhuddttxo', {
  first_name: 'Augusta',
});

Python

from emailit import EmailitClient
client = EmailitClient("your_api_key")

subscriber = client.subscribers.update("aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2", "sub_4KECYl5AwXEy8ezswYRhuddttxo", {
  "first_name": "Augusta",
})

PHP

$emailit = Emailit::client('your_api_key');

$subscriber = $emailit->subscribers()->update('aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2', 'sub_4KECYl5AwXEy8ezswYRhuddttxo', [
  'first_name' => 'Augusta',
]);

Ruby

require "emailit"
client = Emailit::EmailitClient.new("your_api_key")

subscriber = client.subscribers.update("aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2", "sub_4KECYl5AwXEy8ezswYRhuddttxo",
  first_name: "Augusta"
)

import "github.com/emailit/emailit-go/v2"
client := emailit.NewClient("your_api_key")

subscriber, err := client.Subscribers.Update("aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2", "sub_4KECYl5AwXEy8ezswYRhuddttxo", &emailit.UpdateSubscriberRequest{
  FirstName: "Augusta",
})

Rust

use emailit::Emailit;
use emailit::types::UpdateSubscriberParams;

let emailit = Emailit::new("your_api_key");

let subscriber = emailit.subscribers.update("aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2", "sub_4KECYl5AwXEy8ezswYRhuddttxo", UpdateSubscriberParams {
  first_name: Some("Augusta".into()),
  ..Default::default()
}).await?;

Java

import com.emailit.*;
import com.emailit.params.*;

EmailitClient emailit = new EmailitClient("your_api_key");

EmailitObject subscriber = emailit.subscribers().update("aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2", "sub_4KECYl5AwXEy8ezswYRhuddttxo",
  SubscriberUpdateParams.builder()
    .setFirstName("Augusta")
    .build()
);

using Emailit;

var emailit = new EmailitClient("your_api_key");

var subscriber = emailit.Subscribers.Update("aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2", "sub_4KECYl5AwXEy8ezswYRhuddttxo", new SubscriberUpdateOptions {
  FirstName = "Augusta",
});

PHP

use Emailit\Laravel\Facades\Emailit;

$subscriber = Emailit::subscribers()->update('aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2', 'sub_4KECYl5AwXEy8ezswYRhuddttxo', [
  'first_name' => 'Augusta',
]);

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"
}

JSON

{
  "error": "No valid fields provided for update. Provide at least one of: email, first_name, last_name, custom_fields, subscribed"
}

JSON

{
  "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.

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.

engagementstring

unengaged para los suscriptores que se consideran sin interacción en el periodo de la lista, engaged para el resto. Combínalo con subscribed=true para omitir a las personas que ya se dieron de baja.

searchstring

Búsqueda en la dirección de email, el nombre o los apellidos, sin distinguir mayúsculas y minúsculas.

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
`subscribed_at`	fecha	Cuándo empezó por última vez la suscripción.
`last_engaged_at`	fecha	La apertura o el clic más reciente del contacto. Los valores vacíos se ordenan al final.
`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. En los listados, cada uno incluye además last_opened_at, last_clicked_at y last_engaged_at (la apertura, el clic o cualquiera de los dos más reciente del contacto, o null) y unengaged.

total_recordsinteger

El número de suscriptores que coinciden.

next_page_urlstring | null

La ruta de la página siguiente, o null. Conserva subscribed y engagement, 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

JavaScript

import { Emailit } from '@emailit/node';
const emailit = new Emailit('your_api_key');

const subscribers = await emailit.subscribers.list('aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2');

Python

from emailit import EmailitClient
client = EmailitClient("your_api_key")

subscribers = client.subscribers.list("aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2")

PHP

$emailit = Emailit::client('your_api_key');

$subscribers = $emailit->subscribers()->list('aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2');

Ruby

require "emailit"
client = Emailit::EmailitClient.new("your_api_key")

subscribers = client.subscribers.list("aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2")

import "github.com/emailit/emailit-go/v2"
client := emailit.NewClient("your_api_key")

subscribers, err := client.Subscribers.List("aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2", nil)

Rust

use emailit::Emailit;

let emailit = Emailit::new("your_api_key");

let subscribers = emailit.subscribers.list("aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2", None).await?;

Java

import com.emailit.*;

EmailitClient emailit = new EmailitClient("your_api_key");

EmailitObject subscribers = emailit.subscribers().list("aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2");

using Emailit;

var emailit = new EmailitClient("your_api_key");

var subscribers = emailit.Subscribers.List("aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2");

PHP

use Emailit\Laravel\Facades\Emailit;

$subscribers = Emailit::subscribers()->list('aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2');

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,
      "last_opened_at": "2026-10-06T08:14:02.000000Z",
      "last_clicked_at": null,
      "last_engaged_at": "2026-10-06T08:14:02.000000Z",
      "unengaged": false,
      "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",
      "last_opened_at": null,
      "last_clicked_at": null,
      "last_engaged_at": null,
      "unengaged": false,
      "created_at": "2026-09-28T07:55:02.000000Z",
      "updated_at": "2026-09-30T18:11:40.000000Z"
    }
  ],
  "total_records": 2,
  "next_page_url": null,
  "previous_page_url": null,
  "usage": {
    "used": 2,
    "limit": 50000,
    "plan": "pro"
  }
}

JSON

{
  "error": "Audience not found"
}

Actualizar suscriptores de forma masiva

Suscribe, da de baja o quita muchos suscriptores de una lista de contactos.

POST/audiences/{audience_id}/subscribers/bulk

Requiere una clave de API full. Elige los suscriptores por ids, o define all_matching para actuar sobre todas las personas que coincidan con los filtros, hasta 10.000. Cada cambio dispara el mismo evento que cambiar un solo suscriptor: subscriber.updated para suscribir y dar de baja, y subscriber.deleted para eliminar. La baja mantiene a las personas en la lista con subscribed: false; la eliminación quita su pertenencia a la lista y conserva los contactos. Consulta Acciones masivas.

Parámetros de ruta

audience_idstringobligatorio

El ID de la lista (aud_…) o su nombre.

Parámetros del cuerpo

actionstringobligatorio

subscribe, unsubscribe o delete.

idsstring[]

Los ID de los suscriptores (sub_…), hasta 1000. Todos deben pertenecer a la lista; si no, no se cambia nada y la petición devuelve 404 con los ID que faltan en missing.

all_matchingbooleanpor defecto: false

Actúa sobre todos los suscriptores que coincidan con los filtros de abajo, en lugar de sobre ids. Más de 10.000 coincidencias devuelven 422.

engagementstring

Con all_matching: unengaged o engaged. Consulta Contactos sin interacción.

subscribedboolean

Con all_matching: solo las personas suscritas (true) o dadas de baja (false).

searchstring

Con all_matching: búsqueda en la dirección de email, el nombre o los apellidos, sin distinguir mayúsculas y minúsculas.

Devuelve

objectstring

Siempre subscriber_bulk.

actionstring

La acción que enviaste.

audience_idstring

El ID de la lista.

processedinteger

Cuántos suscriptores se seleccionaron.

changedinteger

Cuántos cambiaron. Suscribir a alguien que ya está suscrito no cuenta.

POST/audiences/{audience_id}/subscribers/bulk

JavaScript

const response = await fetch('https://api.emailit.com/v2/audiences/aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2/subscribers/bulk', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer your_api_key',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    action: 'unsubscribe',
    all_matching: true,
    engagement: 'unengaged',
    subscribed: true
  })
});

const { changed } = await response.json();

Terminal

curl -X POST https://api.emailit.com/v2/audiences/aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2/subscribers/bulk \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"action": "unsubscribe", "all_matching": true, "engagement": "unengaged", "subscribed": true}'

JSON

{
  "object": "subscriber_bulk",
  "action": "unsubscribe",
  "audience_id": "aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2",
  "processed": 212,
  "changed": 212
}

JSON

{
  "error": "One or more subscribers were not found",
  "missing": ["sub_4KnmYprkoMRytdkm3tAHIfPW0Vh"]
}

JSON

{
  "error": "More than 10000 subscribers match. Narrow the filter and try again."
}

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}

JavaScript

import { Emailit } from '@emailit/node';
const emailit = new Emailit('your_api_key');

await emailit.subscribers.delete('aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2', 'sub_4KECYl5AwXEy8ezswYRhuddttxo');

Python

from emailit import EmailitClient
client = EmailitClient("your_api_key")

client.subscribers.delete("aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2", "sub_4KECYl5AwXEy8ezswYRhuddttxo")

PHP

$emailit = Emailit::client('your_api_key');

$emailit->subscribers()->delete('aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2', 'sub_4KECYl5AwXEy8ezswYRhuddttxo');

Ruby

require "emailit"
client = Emailit::EmailitClient.new("your_api_key")

client.subscribers.delete("aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2", "sub_4KECYl5AwXEy8ezswYRhuddttxo")

import "github.com/emailit/emailit-go/v2"
client := emailit.NewClient("your_api_key")

err := client.Subscribers.Delete("aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2", "sub_4KECYl5AwXEy8ezswYRhuddttxo")

Rust

use emailit::Emailit;

let emailit = Emailit::new("your_api_key");

emailit.subscribers.delete("aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2", "sub_4KECYl5AwXEy8ezswYRhuddttxo").await?;

Java

import com.emailit.*;

EmailitClient emailit = new EmailitClient("your_api_key");

emailit.subscribers().delete("aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2", "sub_4KECYl5AwXEy8ezswYRhuddttxo");

using Emailit;

var emailit = new EmailitClient("your_api_key");

emailit.Subscribers.Delete("aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2", "sub_4KECYl5AwXEy8ezswYRhuddttxo");

PHP

use Emailit\Laravel\Facades\Emailit;

Emailit::subscribers()->delete('aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2', 'sub_4KECYl5AwXEy8ezswYRhuddttxo');

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
}

JSON

{
  "error": "Subscriber not found"
}