Listas de contactos

Gestiona las listas de suscriptores que usan las campañas y los formularios de suscripción.

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

POST/audiences
GET/audiences/{id}
POST/audiences/{id}
GET/audiences
DEL/audiences/{id}

Crear una lista de contactos

Crea una lista de contactos vacía.

POST/audiences

Requiere una clave de API full. Añade personas con Añadir un suscriptor o pasando el ID de la lista en audiences al crear un contacto. Dispara un evento audience.created. Consulta Listas de contactos.

Parámetros del cuerpo

namestringobligatorio

El nombre de la lista, como Newsletter. Debe ser único en el espacio de trabajo.

Devuelve

Devuelve 201 con la nueva lista:

objectstring

Siempre audience.

idstring

El ID de la lista.

namestring

El nombre de la lista.

tokenstring

El token público de la URL de suscripción alojada de la lista.

created_atstring

Cuándo se creó la lista.

updated_atstring

Cuándo se modificó la lista por última vez.

POST/audiences

JavaScript

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

const audience = await emailit.audiences.create({
  name: 'Newsletter',
});

Python

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

audience = client.audiences.create({
  "name": "Newsletter"
})

PHP

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

$audience = $emailit->audiences()->create([
  'name' => 'Newsletter',
]);

Ruby

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

audience = client.audiences.create(name: "Newsletter")

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

audience, err := client.Audiences.Create(&emailit.CreateAudienceRequest{
  Name: "Newsletter",
})

Rust

use emailit::Emailit;
use emailit::types::CreateAudienceParams;

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

let audience = emailit.audiences.create(
  CreateAudienceParams::new("Newsletter")
).await?;

Java

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

EmailitClient emailit = new EmailitClient("your_api_key");

EmailitObject audience = emailit.audiences().create(
  AudienceCreateParams.builder()
    .setName("Newsletter")
    .build()
);

using Emailit;

var emailit = new EmailitClient("your_api_key");

var audience = emailit.Audiences.Create(new AudienceCreateOptions {
  Name = "Newsletter",
});

PHP

use Emailit\Laravel\Facades\Emailit;

$audience = Emailit::audiences()->create([
  'name' => 'Newsletter',
]);

Terminal

curl -X POST https://api.emailit.com/v2/audiences \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Newsletter"}'

JSON

{
  "object": "audience",
  "id": "aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2",
  "name": "Newsletter",
  "token": "4KXUJdXRVlVgbkWQm4GHLy8BleP",
  "created_at": "2026-10-01T10:02:44.613207Z",
  "updated_at": "2026-10-01T10:02:44.613207Z"
}

JSON

{
  "error": "Audience with this name already exists",
  "existing": {
    "object": "audience",
    "id": "aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2",
    "name": "Newsletter",
    "token": "4KXUJdXRVlVgbkWQm4GHLy8BleP",
    "subscribers_count": 0,
    "created_at": "2026-10-01T10:02:44.000000Z",
    "updated_at": "2026-10-01T10:02:44.000000Z"
  }
}

Obtener una lista de contactos

Obtiene una lista de contactos con su número de suscriptores y su token público.

GET/audiences/{id}

Requiere una clave de API full.

Parámetros de ruta

idstringobligatorio

El ID de la lista (aud_…) o su nombre exacto, codificado para URL.

Devuelve

Devuelve el objeto de lista de contactos.

objectstring

Siempre audience.

idstring

El ID de la lista.

namestring

El nombre de la lista.

tokenstring

El token público de la URL de suscripción alojada de la lista. Trátalo como público: cualquiera que lo tenga puede suscribirse a la lista.

subscribers_countinteger

Cuántos contactos hay en la lista, incluidos los dados de baja.

usageobject

used (el mismo número), limit (el número máximo de suscriptores que puede tener una lista en tu plan, o null si no hay límite) y plan. Consulta Límites.

created_atstring

Cuándo se creó la lista.

updated_atstring

Cuándo se modificó la lista por última vez.

GET/audiences/{id}

JavaScript

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

const audience = await emailit.audiences.get('aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2');

Python

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

audience = client.audiences.get("aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2")

PHP

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

$audience = $emailit->audiences()->get('aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2');

Ruby

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

audience = client.audiences.get("aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2")

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

audience, err := client.Audiences.Get("aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2")

Rust

use emailit::Emailit;

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

let audience = emailit.audiences.get("aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2").await?;

Java

import com.emailit.*;

EmailitClient emailit = new EmailitClient("your_api_key");

EmailitObject audience = emailit.audiences().get("aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2");

using Emailit;

var emailit = new EmailitClient("your_api_key");

var audience = emailit.Audiences.Get("aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2");

PHP

use Emailit\Laravel\Facades\Emailit;

$audience = Emailit::audiences()->get('aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2');

Terminal

curl https://api.emailit.com/v2/audiences/aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2 \
  -H "Authorization: Bearer $EMAILIT_API_KEY"

JSON

{
  "object": "audience",
  "id": "aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2",
  "name": "Newsletter",
  "token": "4KXUJdXRVlVgbkWQm4GHLy8BleP",
  "subscribers_count": 1284,
  "usage": {
    "used": 1284,
    "limit": 50000,
    "plan": "pro"
  },
  "created_at": "2026-10-01T10:02:44.000000Z",
  "updated_at": "2026-10-01T10:02:44.000000Z"
}

JSON

{
  "error": "Audience not found"
}

Actualizar una lista de contactos

Cambia el nombre de una lista de contactos.

POST/audiences/{id}

Requiere una clave de API full. El ID, el token y los suscriptores no cambian. Dispara un evento audience.updated.

Parámetros de ruta

idstringobligatorio

El ID de la lista o su nombre actual.

Parámetros del cuerpo

namestringobligatorio

El nuevo nombre. Debe ser único en el espacio de trabajo.

Devuelve

Devuelve la lista con object, id, name, token, subscribers_count, created_at y updated_at. En esta respuesta, subscribers_count siempre es 0; para el número real, usa Obtener una lista de contactos.

POST/audiences/{id}

JavaScript

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

const audience = await emailit.audiences.update('aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2', {
  name: 'Weekly newsletter',
});

Python

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

audience = client.audiences.update("aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2", {
  "name": "Weekly newsletter"
})

PHP

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

$audience = $emailit->audiences()->update('aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2', [
  'name' => 'Weekly newsletter',
]);

Ruby

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

audience = client.audiences.update("aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2", name: "Weekly newsletter")

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

audience, err := client.Audiences.Update("aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2", &emailit.UpdateAudienceRequest{
  Name: "Weekly newsletter",
})

Rust

use emailit::Emailit;
use emailit::types::UpdateAudienceParams;

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

let audience = emailit.audiences.update("aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2", UpdateAudienceParams {
  name: Some("Weekly newsletter".into()),
  ..Default::default()
}).await?;

Java

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

EmailitClient emailit = new EmailitClient("your_api_key");

EmailitObject audience = emailit.audiences().update("aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2",
  AudienceUpdateParams.builder()
    .setName("Weekly newsletter")
    .build()
);

using Emailit;

var emailit = new EmailitClient("your_api_key");

var audience = emailit.Audiences.Update("aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2", new AudienceUpdateOptions {
  Name = "Weekly newsletter",
});

PHP

use Emailit\Laravel\Facades\Emailit;

$audience = Emailit::audiences()->update('aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2', [
  'name' => 'Weekly newsletter',
]);

Terminal

curl -X POST https://api.emailit.com/v2/audiences/aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2 \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Weekly newsletter"}'

JSON

{
  "object": "audience",
  "id": "aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2",
  "name": "Weekly newsletter",
  "token": "4KXUJdXRVlVgbkWQm4GHLy8BleP",
  "subscribers_count": 0,
  "created_at": "2026-10-01T10:02:44.000000Z",
  "updated_at": "2026-10-01T14:31:09.000000Z"
}

JSON

{
  "error": "No valid fields provided for update. Provide at least one of: name"
}

JSON

{
  "error": "Audience not found"
}

JSON

{
  "error": "Another audience with this name already exists"
}

Listar listas de contactos

Devuelve una página de listas de contactos, de la más reciente a la más antigua.

GET/audiences

Requiere una clave de API full. Los elementos del listado no incluyen el token de la lista; para obtenerlo, usa Obtener una lista de contactos.

Parámetros de consulta

pageintegerpor defecto: 1

La página que se devuelve.

limitintegerpor defecto: 10

Listas por página, de 1 a 100.

searchstring

Búsqueda en el nombre de la lista, sin distinguir mayúsculas y minúsculas.

matchstringpor defecto: all

all u or. Cómo se combinan los filtros de abajo.

orderstring

name o created_at.

directionstring

asc o desc.

Filtros

Añade filtros con el formato key.condition=value, por ejemplo name.contains=news. Consulta Filtrado.

Clave	Tipo
`name`	cadena
`created_at`	fecha

Devuelve

dataobject[]

Las listas de esta página, cada una con object, id, name, subscribers_count, usage, created_at y updated_at. Consulta Obtener una lista de contactos.

total_recordsinteger

El número de listas del espacio de trabajo.

next_page_urlstring | null

La ruta de la página siguiente, o null. Consulta Paginación.

previous_page_urlstring | null

La ruta de la página anterior, o null.

GET/audiences

JavaScript

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

const audiences = await emailit.audiences.list();

Python

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

audiences = client.audiences.list()

PHP

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

$audiences = $emailit->audiences()->list();

Ruby

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

audiences = client.audiences.list

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

audiences, err := client.Audiences.List(nil)

Rust

use emailit::Emailit;

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

let audiences = emailit.audiences.list(None).await?;

Java

import com.emailit.*;

EmailitClient emailit = new EmailitClient("your_api_key");

EmailitObject audiences = emailit.audiences().list();

using Emailit;

var emailit = new EmailitClient("your_api_key");

var audiences = emailit.Audiences.List();

PHP

use Emailit\Laravel\Facades\Emailit;

$audiences = Emailit::audiences()->list();

Terminal

curl https://api.emailit.com/v2/audiences \
  -H "Authorization: Bearer $EMAILIT_API_KEY"

JSON

{
  "data": [
    {
      "object": "audience",
      "id": "aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2",
      "name": "Newsletter",
      "subscribers_count": 1284,
      "usage": {
        "used": 1284,
        "limit": 50000,
        "plan": "pro"
      },
      "created_at": "2026-10-01T10:02:44.000000Z",
      "updated_at": "2026-10-01T10:02:44.000000Z"
    },
    {
      "object": "audience",
      "id": "aud_4KOlh9t2uw5od4qypqCtyrZyDq2",
      "name": "Customers",
      "subscribers_count": 312,
      "usage": {
        "used": 312,
        "limit": 50000,
        "plan": "pro"
      },
      "created_at": "2026-09-20T16:45:10.000000Z",
      "updated_at": "2026-09-20T16:45:10.000000Z"
    }
  ],
  "total_records": 2,
  "next_page_url": null,
  "previous_page_url": null
}

Eliminar una lista de contactos

Elimina de forma permanente una lista de contactos y quita de ella a todos sus suscriptores.

DELETE/audiences/{id}

Requiere una clave de API full. Las pertenencias de los suscriptores a la lista se eliminan con ella, pero los contactos siguen en tu espacio de trabajo y en sus otras listas. Su URL de suscripción alojada deja de funcionar. Dispara un evento audience.deleted. No se envían eventos subscriber.deleted por las pertenencias eliminadas.

Parámetros de ruta

idstringobligatorio

El ID o el nombre de la lista.

Devuelve

objectstring

Siempre audience.

idstring

El ID de la lista eliminada.

namestring

El nombre de la lista.

deletedboolean

Siempre true.

DELETE/audiences/{id}

JavaScript

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

await emailit.audiences.delete('aud_4KOlh9t2uw5od4qypqCtyrZyDq2');

Python

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

client.audiences.delete("aud_4KOlh9t2uw5od4qypqCtyrZyDq2")

PHP

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

$emailit->audiences()->delete('aud_4KOlh9t2uw5od4qypqCtyrZyDq2');

Ruby

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

client.audiences.delete("aud_4KOlh9t2uw5od4qypqCtyrZyDq2")

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

err := client.Audiences.Delete("aud_4KOlh9t2uw5od4qypqCtyrZyDq2")

Rust

use emailit::Emailit;

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

emailit.audiences.delete("aud_4KOlh9t2uw5od4qypqCtyrZyDq2").await?;

Java

import com.emailit.*;

EmailitClient emailit = new EmailitClient("your_api_key");

emailit.audiences().delete("aud_4KOlh9t2uw5od4qypqCtyrZyDq2");

using Emailit;

var emailit = new EmailitClient("your_api_key");

emailit.Audiences.Delete("aud_4KOlh9t2uw5od4qypqCtyrZyDq2");

PHP

use Emailit\Laravel\Facades\Emailit;

Emailit::audiences()->delete('aud_4KOlh9t2uw5od4qypqCtyrZyDq2');

Terminal

curl -X DELETE https://api.emailit.com/v2/audiences/aud_4KOlh9t2uw5od4qypqCtyrZyDq2 \
  -H "Authorization: Bearer $EMAILIT_API_KEY"

JSON

{
  "object": "audience",
  "id": "aud_4KOlh9t2uw5od4qypqCtyrZyDq2",
  "name": "Customers",
  "deleted": true
}

JSON

{
  "error": "Audience not found"
}