Inscritos

Adicione, atualize e remova os inscritos de uma lista de contatos.

URL basehttps://api.emailit.com/v2Autenticação Erros Limites de requisições

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}

Adicionar um inscrito

Adiciona um contato a uma lista de contatos pelo endereço de e-mail.

POST/audiences/{audience_id}/subscribers

Requer uma chave de API com escopo full. Se ainda não houver um contato com esse e-mail, o Emailit cria um. Se o contato existir, o nome, o sobrenome e os campos personalizados que você enviar substituem os valores atuais dele. Um contato que tinha se descadastrado da lista é inscrito de novo, e a resposta é 200; um contato que já está inscrito retorna 409.

Cada lista de contatos pode ter tantos inscritos quanto o seu plano permitir; acima disso, a requisição retorna 422 com o seu usage. Dispara subscriber.created, ou subscriber.updated e subscriber.resubscribed em uma reinscrição.

Com double_opt_in, a pessoa recebe o e-mail de double opt-in da lista e entra nela quando clica no link, então a resposta é 202 e ainda não existe nenhum inscrito.

Parâmetros de caminho

audience_idstringobrigatório

O ID da lista de contatos (aud_…) ou o nome dela.

Parâmetros do corpo

emailstringobrigatório

O endereço de e-mail a inscrever. Armazenado em minúsculas.

first_namestring

O nome do contato.

last_namestring

O sobrenome do contato.

custom_fieldsobject

Valores de campos personalizados por chave, como {"company": "Analytical Engines"}. Substitui os campos personalizados existentes do contato.

double_opt_inbooleanpadrão: false

Envia o e-mail de double opt-in em vez de inscrever a pessoa na hora. A lista precisa ter o double opt-in ativado; caso contrário, a requisição retorna 422. Uma pessoa que já está inscrita recebe 409, como de costume.

send_confirmation_emailbooleanpadrão: false

Envia o e-mail de confirmação da lista depois da inscrição, quando a lista tem esse e-mail ativado.

Retorno

Retorna 201 com o objeto de inscrito, ou 200 quando um contato descadastrado foi inscrito de novo. Com double_opt_in, retorna 202 com object: "subscriber_confirmation", status: "pending", audience_id, contact_id e email. Se não for possível enviar o e-mail de double opt-in, a requisição retorna 422 com um code como unverified_domain ou 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"
  }
}

Obter um inscrito

Obtém a participação de um contato em uma lista de contatos.

GET/audiences/{audience_id}/subscribers/{id}

Requer uma chave de API com escopo full. Um inscrito liga um contato a uma lista de contatos. O e-mail, os nomes e os campos personalizados pertencem ao contato, e subscribed vale apenas para esta lista.

Parâmetros de caminho

audience_idstringobrigatório

O ID da lista de contatos (aud_…) ou o nome dela.

idstringobrigatório

O ID do inscrito (sub_…) ou o endereço de e-mail do contato, codificado para URL.

Retorno

Retorna o objeto de inscrito.

objectstring

Sempre subscriber.

idstring

O ID do inscrito.

audience_idstring

O ID da lista de contatos.

contact_idstring

O ID do contato.

emailstring

O endereço de e-mail do contato.

first_namestring | null

O nome do contato.

last_namestring | null

O sobrenome do contato.

custom_fieldsobject | null

Os valores dos campos personalizados do contato.

subscribedboolean

true se o contato estiver inscrito nesta lista, false se tiver se descadastrado.

subscribed_atstring | null

Quando o contato se inscreveu pela última vez.

unsubscribed_atstring | null

Quando o contato se descadastrou, ou null.

created_atstring

Quando o contato entrou na lista.

updated_atstring

Quando a participação mudou pela ú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"
}

Atualizar um inscrito

Altera o status de um inscrito na lista de contatos ou os dados do contato dele.

POST/audiences/{audience_id}/subscribers/{id}

Requer uma chave de API com escopo full. Envie apenas os campos que você quer alterar. subscribed vale apenas para esta lista. email, first_name, last_name e custom_fields alteram o próprio contato, então a mudança aparece em todas as listas de que o contato participa. Dispara um evento subscriber.updated.

Parâmetros de caminho

audience_idstringobrigatório

O ID da lista de contatos (aud_…) ou o nome dela.

idstringobrigatório

O ID do inscrito (sub_…) ou o endereço de e-mail do contato, codificado para URL.

Parâmetros do corpo

subscribedboolean

false para descadastrar o contato desta lista, true para inscrevê-lo de novo. O inscrito continua na lista nos dois casos.

emailstring

Um novo endereço de e-mail para o contato. Armazenado em minúsculas.

first_namestring

O nome do contato.

last_namestring

O sobrenome do contato.

custom_fieldsobject

Valores de campos personalizados por chave. Substitui os campos personalizados existentes do contato.

Retorno

Retorna o objeto de inscrito atualizado. Uma requisição sem nenhum desses campos retorna 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 inscritos

Retorna uma página de inscritos de uma lista de contatos, dos mais recentes para os mais antigos.

GET/audiences/{audience_id}/subscribers

Requer uma chave de API com escopo full. A listagem inclui os contatos que se descadastraram da lista, a menos que você os exclua com subscribed=true.

Parâmetros de caminho

audience_idstringobrigatório

O ID da lista de contatos (aud_…) ou o nome dela.

Parâmetros de consulta

pageintegerpadrão: 1

A página a retornar.

limitintegerpadrão: 25

Inscritos por página, de 1 a 100. per_page também funciona.

subscribedstring

true para apenas os contatos inscritos, false para apenas os descadastrados.

engagementstring

unengaged para os inscritos que contam como não engajados no período da lista, engaged para os demais. Combine com subscribed=true para deixar de fora as pessoas que já se descadastraram.

searchstring

Busca sem diferenciar maiúsculas de minúsculas no endereço de e-mail, no nome ou no sobrenome.

matchstringpadrão: all

all ou or. Como os filtros abaixo se combinam.

orderstring

Uma chave de filtro pela qual ordenar.

directionstring

asc ou desc.

Filtros

Adicione filtros no formato key.condition=value, por exemplo email.ends_with=@acme.com. Consulte Filtragem.

Chave	Tipo	Observações
`email`	string
`first_name`	string
`last_name`	string
`subscribed`	boolean
`subscribed_at`	date	Quando a inscrição começou pela última vez.
`last_engaged_at`	date	A abertura ou o clique mais recente do contato. Os valores vazios ficam por último na ordenação.
`created_at`	date	Quando o contato entrou na lista.

Toda chave também serve para ordenar.

Retorno

dataobject[]

Os objetos de inscrito desta página. Nas listagens, cada um também tem last_opened_at, last_clicked_at e last_engaged_at (a abertura mais recente, o clique mais recente e o mais recente dos dois para o contato, ou null) e unengaged.

total_recordsinteger

O número de inscritos que correspondem à consulta.

next_page_urlstring | null

Caminho da próxima página, ou null. Mantém subscribed e engagement, mas não os seus outros filtros. Consulte Paginação.

previous_page_urlstring | null

Caminho da página anterior, ou null.

usageobject

used (inscritos na lista), limit (o máximo que o seu plano permite por lista, ou null) e 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"
}

Atualizar inscritos em massa

Inscreve, descadastra ou remove muitos inscritos de uma lista de contatos.

POST/audiences/{audience_id}/subscribers/bulk

Requer uma chave de API com escopo full. Escolha os inscritos por ids ou defina all_matching para agir sobre todas as pessoas que correspondem aos filtros, até 10.000 pessoas. Cada alteração dispara o mesmo evento que a alteração de um único inscrito: subscriber.updated para inscrever e descadastrar, subscriber.deleted para excluir. Descadastrar mantém as pessoas na lista com subscribed: false; excluir remove a participação delas na lista e mantém os contatos. Consulte Ações em massa.

Parâmetros de caminho

audience_idstringobrigatório

O ID da lista de contatos (aud_…) ou o nome dela.

Parâmetros do corpo

actionstringobrigatório

subscribe, unsubscribe ou delete.

idsstring[]

IDs de inscritos (sub_…), até 1.000. Todos devem pertencer à lista; caso contrário, nada é alterado e a requisição retorna 404 com os IDs ausentes em missing.

all_matchingbooleanpadrão: false

Age sobre todos os inscritos que correspondem aos filtros abaixo, em vez de ids. Mais de 10.000 correspondências retornam 422.

engagementstring

Com all_matching: unengaged ou engaged. Consulte Contatos não engajados.

subscribedboolean

Com all_matching: apenas as pessoas inscritas (true) ou descadastradas (false).

searchstring

Com all_matching: busca sem diferenciar maiúsculas de minúsculas no endereço de e-mail, no nome ou no sobrenome.

Retorno

objectstring

Sempre subscriber_bulk.

actionstring

A ação que você enviou.

audience_idstring

O ID da lista de contatos.

processedinteger

Quantos inscritos foram selecionados.

changedinteger

Quantos foram alterados. Inscrever alguém que já está inscrito não conta.

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

Excluir um inscrito

Remove um contato de uma lista de contatos.

DELETE/audiences/{audience_id}/subscribers/{id}

Requer uma chave de API com escopo full. O contato em si não é excluído e continua nas outras listas dele. Para manter o registro de que a pessoa cancelou o opt-in, descadastre-a com subscribed: false em vez de excluí-la. Dispara um evento subscriber.deleted.

Parâmetros de caminho

audience_idstringobrigatório

O ID da lista de contatos (aud_…) ou o nome dela.

idstringobrigatório

O ID do inscrito (sub_…) ou o endereço de e-mail do contato, codificado para URL.

Retorno

objectstring

Sempre subscriber.

idstring

O ID do inscrito excluído.

audience_idstring

O ID da lista de contatos.

contact_idstring

O ID do contato.

emailstring

O endereço de e-mail do contato.

deletedboolean

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