Listas de contatos

Gerencie as listas de inscritos usadas por campanhas e formulários de inscrição.

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

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

Criar uma lista de contatos

Cria uma lista de contatos vazia.

POST/audiences

Requer uma chave de API com escopo full. Adicione pessoas com Adicionar um inscrito ou passando o ID da lista em audiences ao criar um contato. Dispara um evento audience.created. Consulte Listas de contatos.

Parâmetros do corpo

namestringobrigatório

O nome da lista, como Newsletter. Deve ser único no workspace.

visibilitystringpadrão: private

public mostra a lista na página de gerenciamento de inscrições para todos; private, apenas para as pessoas inscritas nela.

public_namestring | null

O nome que os inscritos veem nos e-mails e nas páginas para destinatários. Até 120 caracteres. Com null, aparece name.

public_descriptionstring | null

Uma linha mostrada na página de gerenciamento de inscrições. Até 500 caracteres.

double_opt_inboolean | object

true ou false, ou um objeto com qualquer um destes campos: enabled, redirect_url (uma URL http(s) para onde as pessoas vão depois de confirmar, ou null) e email. email aceita from, reply_to, subject, design (default ou custom), heading, body, button_label e footer. Os campos que você omitir mantêm o valor armazenado. Para ativá-lo, é preciso um endereço from em um domínio de envio verificado. Consulte Double opt-in.

confirmation_emailboolean | object

true ou false, ou um objeto com enabled e email, que aceita os mesmos campos acima e também button_url.

unengagedobject

exclude (deixar de fora os inscritos não engajados nas campanhas) e days (de 30 a 1.825).

Retorno

Retorna 201 com a nova lista de contatos, incluindo as configurações dela, conforme descrito em Obter uma lista de contatos:

objectstring

Sempre audience.

idstring

O ID da lista de contatos.

namestring

O nome da lista de contatos.

tokenstring

O token da URL de inscrição da lista. Mantenha-o em segredo.

visibilitystring

public ou private.

created_atstring

Quando a lista foi criada.

updated_atstring

Quando a lista foi alterada pela ú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",
  "visibility": "private",
  "public_name": null,
  "public_description": null,
  "double_opt_in": {
    "enabled": false,
    "redirect_url": null,
    "email": {
      "from": null,
      "reply_to": null,
      "subject": "Confirm your subscription to {{audience_name}}",
      "design": "default",
      "heading": "Please confirm your subscription",
      "body": "Hi {{first_name|\"there\"}},\n\nYou asked to join {{audience_name}}. Confirm your email address to start getting our emails.",
      "button_label": "Confirm subscription",
      "footer": "Button not working? Open this link: <a href=\"{{confirm_url}}\">{{confirm_url}}</a>\n\nIf you did not ask to subscribe, ignore this email. You will not be added unless you confirm.",
      "source": null
    }
  },
  "confirmation_email": {
    "enabled": false,
    "email": {
      "from": null,
      "reply_to": null,
      "subject": "You're subscribed to {{audience_name}}",
      "design": "default",
      "heading": "You're subscribed",
      "body": "Hi {{first_name|\"there\"}},\n\nThanks for joining {{audience_name}}. You will hear from us soon.",
      "button_label": "",
      "button_url": "",
      "footer": "You are getting this email because you subscribed to {{audience_name}}. <a href=\"{{manage_subscriptions_url}}\">Manage subscriptions</a>",
      "source": null
    }
  },
  "unengaged": { "exclude": false, "days": 365 },
  "archived": false,
  "archived_at": null,
  "subscribers_count": 0,
  "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"
  }
}

Obter uma lista de contatos

Obtém uma lista de contatos com as configurações, as contagens e o token público.

GET/audiences/{id}

Requer uma chave de API com escopo full.

Parâmetros de caminho

idstringobrigatório

O ID da lista de contatos (aud_…) ou o nome exato dela, codificado para URL.

Retorno

Retorna o objeto da lista de contatos.

objectstring

Sempre audience.

idstring

O ID da lista de contatos.

namestring

O nome da lista de contatos.

tokenstring

O token da URL de inscrição da lista. Mantenha-o em segredo: qualquer pessoa que o tenha pode adicionar pessoas à lista.

visibilitystring

public ou private. As listas públicas aparecem na página de gerenciamento de inscrições para todos; as privadas, apenas para as pessoas inscritas nelas.

public_namestring | null

O nome que os inscritos veem, ou null para mostrar name.

public_descriptionstring | null

A descrição mostrada na página de gerenciamento de inscrições.

double_opt_inobject

enabled, redirect_url (para onde as pessoas vão depois de confirmar, ou null) e email, o e-mail de double opt-in, com from, reply_to, subject, design (default ou custom), heading, body, button_label, footer e source (o MJML de um design personalizado, ou null; as listagens o omitem). Os campos que você nunca definiu contêm os valores padrão.

confirmation_emailobject

enabled e email, o e-mail de confirmação, com os mesmos campos acima e também button_url.

unengagedobject

exclude (se as campanhas deixam de fora os inscritos não engajados) e days (o período, 365 por padrão).

archivedboolean

Se a lista está arquivada. archived_at contém o horário, ou null.

subscribers_countinteger

Quantos contatos estão na lista, incluindo os descadastrados.

usageobject

used (a mesma contagem), limit (o número máximo de inscritos que uma lista pode ter no seu plano, ou null se não houver limite) e plan. Consulte Limites.

unengaged_countinteger

Quantos membros inscritos contam como não engajados neste momento.

pending_confirmations_countinteger

Quantas solicitações de double opt-in estão aguardando um clique, sem contar as expiradas.

created_atstring

Quando a lista foi criada.

updated_atstring

Quando a lista foi alterada pela ú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",
  "visibility": "public",
  "public_name": "Monthly newsletter",
  "public_description": "Product news and tips, once a month.",
  "double_opt_in": {
    "enabled": true,
    "redirect_url": null,
    "email": {
      "from": "News <news@example.com>",
      "reply_to": null,
      "subject": "Confirm your subscription to {{audience_name}}",
      "design": "default",
      "heading": "Please confirm your subscription",
      "body": "Hi {{first_name|\"there\"}},\n\nYou asked to join {{audience_name}}. Confirm your email address to start getting our emails.",
      "button_label": "Confirm subscription",
      "footer": "Button not working? Open this link: <a href=\"{{confirm_url}}\">{{confirm_url}}</a>\n\nIf you did not ask to subscribe, ignore this email. You will not be added unless you confirm.",
      "source": null
    }
  },
  "confirmation_email": {
    "enabled": false,
    "email": {
      "from": null,
      "reply_to": null,
      "subject": "You're subscribed to {{audience_name}}",
      "design": "default",
      "heading": "You're subscribed",
      "body": "Hi {{first_name|\"there\"}},\n\nThanks for joining {{audience_name}}. You will hear from us soon.",
      "button_label": "",
      "footer": "You are getting this email because you subscribed to {{audience_name}}. <a href=\"{{manage_subscriptions_url}}\">Manage subscriptions</a>",
      "button_url": "",
      "source": null
    }
  },
  "unengaged": { "exclude": true, "days": 365 },
  "archived": false,
  "archived_at": null,
  "token": "4KXUJdXRVlVgbkWQm4GHLy8BleP",
  "subscribers_count": 1284,
  "unengaged_count": 212,
  "pending_confirmations_count": 3,
  "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"
}

Atualizar uma lista de contatos

Renomeia uma lista de contatos ou altera as configurações dela.

POST/audiences/{id}

Requer uma chave de API com escopo full. Envie apenas os campos que você quer alterar. O ID, o token e os inscritos não mudam. Dispara um evento audience.updated.

Parâmetros de caminho

idstringobrigatório

O ID da lista de contatos ou o nome atual dela.

Parâmetros do corpo

namestring

O novo nome. Deve ser único no workspace.

visibilitystring

public mostra a lista na página de gerenciamento de inscrições para todos; private, apenas para as pessoas inscritas nela.

public_namestring | null

O nome que os inscritos veem nos e-mails e nas páginas para destinatários. Até 120 caracteres. Com null, aparece name.

public_descriptionstring | null

Uma linha mostrada na página de gerenciamento de inscrições. Até 500 caracteres.

double_opt_inboolean | object

confirmation_emailboolean | object

true ou false, ou um objeto com enabled e email, que aceita os mesmos campos acima e também button_url.

unengagedobject

exclude (deixar de fora os inscritos não engajados nas campanhas) e days (de 30 a 1.825).

archivedboolean

true arquiva a lista, false a desarquiva. Consulte Arquivar uma lista.

Definir um design MJML personalizado com email.source faz parte da fase alfa do MJML e retorna 403 com error: "mjml_alpha" para chaves de API.

Retorno

Retorna a lista de contatos com as configurações dela, como em Obter uma lista de contatos. Nesta resposta, subscribers_count é sempre 0, e as contagens ficam de fora; use Obter uma lista de contatos para consultá-las. Configurações inválidas retornam 422 com um objeto errors indexado por campo, como double_opt_in.email.from.

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",
  "visibility": "public",
  "public_name": "Weekly newsletter",
  "public_description": null,
  "double_opt_in": {
    "enabled": true,
    "redirect_url": null,
    "email": {
      "from": "News <news@example.com>",
      "reply_to": null,
      "subject": "Confirm your subscription to {{audience_name}}",
      "design": "default",
      "heading": "Please confirm your subscription",
      "body": "Hi {{first_name|\"there\"}},\n\nYou asked to join {{audience_name}}. Confirm your email address to start getting our emails.",
      "button_label": "Confirm subscription",
      "footer": "Button not working? Open this link: <a href=\"{{confirm_url}}\">{{confirm_url}}</a>\n\nIf you did not ask to subscribe, ignore this email. You will not be added unless you confirm.",
      "source": null
    }
  },
  "confirmation_email": {
    "enabled": false,
    "email": {
      "from": null,
      "reply_to": null,
      "subject": "You're subscribed to {{audience_name}}",
      "design": "default",
      "heading": "You're subscribed",
      "body": "Hi {{first_name|\"there\"}},\n\nThanks for joining {{audience_name}}. You will hear from us soon.",
      "button_label": "",
      "button_url": "",
      "footer": "You are getting this email because you subscribed to {{audience_name}}. <a href=\"{{manage_subscriptions_url}}\">Manage subscriptions</a>",
      "source": null
    }
  },
  "unengaged": {
    "exclude": false,
    "days": 365
  },
  "archived": false,
  "archived_at": null,
  "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, visibility, public_name, public_description, double_opt_in, confirmation_email, unengaged, archived"
}

JSON

{
  "message": "Validation failed.",
  "errors": {
    "double_opt_in.email.from": ["Use an address on a verified sending domain of this workspace."]
  }
}

JSON

{
  "error": "Audience not found"
}

JSON

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

Listar listas de contatos

Retorna uma página de listas de contatos, das mais recentes para as mais antigas. As listas arquivadas ficam de fora, a menos que você as peça.

GET/audiences

Requer uma chave de API com escopo full. Os itens da listagem não incluem o token da lista; use Obter uma lista de contatos para obtê-lo.

Parâmetros de consulta

pageintegerpadrão: 1

A página a retornar.

limitintegerpadrão: 10

Listas de contatos por página, de 1 a 100.

searchstring

Busca sem diferenciar maiúsculas de minúsculas no nome da lista.

archivedstringpadrão: false

false para as listas ativas, true apenas para as arquivadas, all para as duas.

visibilitystring

public ou private para listar apenas essas.

matchstringpadrão: all

all ou or. Como os filtros abaixo se combinam.

orderstring

name, public_name, visibility, subscribers_count ou created_at.

directionstring

asc ou desc.

Filtros

Adicione filtros no formato key.condition=value, por exemplo name.contains=news. Consulte Filtragem.

Chave	Tipo
`name`	string
`public_name`	string
`visibility`	enum: `public`, `private`
`subscribers_count`	number
`created_at`	date

Retorno

dataobject[]

As listas de contatos desta página, cada uma com object, id, name, as configurações (visibility, public_name, public_description, double_opt_in, confirmation_email, unengaged, archived, archived_at), subscribers_count, usage, created_at e updated_at. Consulte Obter uma lista de contatos. Os objetos email das listagens não incluem source.

total_recordsinteger

O número de listas de contatos que correspondem à busca, aos filtros e a archived.

next_page_urlstring | null

Caminho da próxima página, ou null. Consulte Paginação.

previous_page_urlstring | null

Caminho da página anterior, ou 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",
      "visibility": "public",
      "public_name": "Monthly newsletter",
      "public_description": "Product news and tips, once a month.",
      "double_opt_in": {
        "enabled": true,
        "redirect_url": null,
        "email": {
          "from": "News <news@example.com>",
          "reply_to": null,
          "subject": "Confirm your subscription to {{audience_name}}",
          "design": "default",
          "heading": "Please confirm your subscription",
          "body": "Hi {{first_name|\"there\"}},\n\nYou asked to join {{audience_name}}. Confirm your email address to start getting our emails.",
          "button_label": "Confirm subscription",
          "footer": "Button not working? Open this link: <a href=\"{{confirm_url}}\">{{confirm_url}}</a>\n\nIf you did not ask to subscribe, ignore this email. You will not be added unless you confirm."
        }
      },
      "confirmation_email": {
        "enabled": false,
        "email": {
          "from": "News <news@example.com>",
          "reply_to": null,
          "subject": "You're subscribed to {{audience_name}}",
          "design": "default",
          "heading": "You're subscribed",
          "body": "Hi {{first_name|\"there\"}},\n\nThanks for joining {{audience_name}}. You will hear from us soon.",
          "button_label": "",
          "footer": "You are getting this email because you subscribed to {{audience_name}}. <a href=\"{{manage_subscriptions_url}}\">Manage subscriptions</a>",
          "button_url": ""
        }
      },
      "unengaged": {
        "exclude": false,
        "days": 365
      },
      "archived": false,
      "archived_at": null,
      "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",
      "visibility": "private",
      "public_name": null,
      "public_description": null,
      "double_opt_in": {
        "enabled": false,
        "redirect_url": null,
        "email": {
          "from": null,
          "reply_to": null,
          "subject": "Confirm your subscription to {{audience_name}}",
          "design": "default",
          "heading": "Please confirm your subscription",
          "body": "Hi {{first_name|\"there\"}},\n\nYou asked to join {{audience_name}}. Confirm your email address to start getting our emails.",
          "button_label": "Confirm subscription",
          "footer": "Button not working? Open this link: <a href=\"{{confirm_url}}\">{{confirm_url}}</a>\n\nIf you did not ask to subscribe, ignore this email. You will not be added unless you confirm."
        }
      },
      "confirmation_email": {
        "enabled": false,
        "email": {
          "from": null,
          "reply_to": null,
          "subject": "You're subscribed to {{audience_name}}",
          "design": "default",
          "heading": "You're subscribed",
          "body": "Hi {{first_name|\"there\"}},\n\nThanks for joining {{audience_name}}. You will hear from us soon.",
          "button_label": "",
          "footer": "You are getting this email because you subscribed to {{audience_name}}. <a href=\"{{manage_subscriptions_url}}\">Manage subscriptions</a>",
          "button_url": ""
        }
      },
      "unengaged": {
        "exclude": false,
        "days": 365
      },
      "archived": false,
      "archived_at": null,
      "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
}

Mesclar listas de contatos

Copia os inscritos de outras listas de contatos para esta.

POST/audiences/{id}/merge

Requer uma chave de API com escopo full. As pessoas que já estão na lista de destino mantêm o status que têm nela, então ninguém que se descadastrou é inscrito de novo. Uma pessoa que está em várias das listas mescladas entra com Subscribed ativado quando está inscrita em pelo menos uma delas. Com delete_sources, as listas mescladas são excluídas em seguida, e as campanhas que ainda não terminaram de ser enviadas (rascunhos, campanhas agendadas, na fila e em envio, e testes A/B aguardando o vencedor) passam a ser enviadas à lista de destino. Se uma dessas campanhas incluía uma lista mesclada e excluía outra, a lista de destino continua incluída. Os segmentos que têm uma lista apagada como origem, ou uma regra sobre ela, passam a usar a lista de destino, assim como os gatilhos, as etapas, as condições e as condições de saída de automações que a mencionam. Isso também vale para os formulários que adicionam pessoas a ela ou a oferecem como opção, os links de double opt-in que ainda não foram confirmados e as execuções de automações que aguardam uma condição sobre ela. Cada exclusão dispara audience.deleted.

A mesclagem não dispara eventos subscriber.*, não inicia automações e não envia e-mails de double opt-in nem de confirmação. Se os novos inscritos fizerem a lista de destino ultrapassar o limite de inscritos do seu plano, nada é mesclado e a requisição retorna 422 com o seu usage. Uma entrada inválida, como mesclar uma lista nela mesma, também retorna 422. Consulte Mesclar listas.

Parâmetros de caminho

idstringobrigatório

A lista de destino da mesclagem, pelo ID ou pelo nome.

Parâmetros do corpo

source_idsstring[]obrigatório

IDs das listas a mesclar, de 1 a 50. Não pode incluir a lista de destino.

delete_sourcesbooleanpadrão: false

Exclui as listas mescladas depois de copiar os inscritos delas.

Retorno

objectstring

Sempre audience_merge.

audienceobject

A lista de destino: object, id, name e o novo subscribers_count dela.

addedinteger

Quantas pessoas entraram na lista de destino.

already_in_audienceinteger

Quantas pessoas das listas mescladas já estavam na lista de destino e mantiveram o status.

deleted_source_idsstring[]

As listas que foram excluídas, ou um array vazio.

POST/audiences/{id}/merge

JavaScript

const response = await fetch('https://api.emailit.com/v2/audiences/aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2/merge', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer your_api_key',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    source_ids: ['aud_4KOlh9t2uw5od4qypqCtyrZyDq2'],
    delete_sources: true
  })
});

const { added, already_in_audience } = await response.json();

Terminal

curl -X POST https://api.emailit.com/v2/audiences/aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2/merge \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"source_ids": ["aud_4KOlh9t2uw5od4qypqCtyrZyDq2"], "delete_sources": true}'

JSON

{
  "object": "audience_merge",
  "audience": {
    "object": "audience",
    "id": "aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2",
    "name": "Newsletter",
    "subscribers_count": 1503
  },
  "added": 219,
  "already_in_audience": 93,
  "deleted_source_ids": ["aud_4KOlh9t2uw5od4qypqCtyrZyDq2"]
}

JSON

{
  "error": "One or more audiences were not found",
  "missing": ["aud_4KOlh9t2uw5od4qypqCtyrZyDq2"]
}

JSON

{
  "message": "Validation failed.",
  "errors": {
    "source_ids": ["An audience cannot be merged into itself."]
  }
}

Atualizar listas de contatos em massa

Arquiva, desarquiva ou exclui várias listas de contatos de uma vez.

POST/audiences/bulk

Requer uma chave de API com escopo full. Todos os IDs devem pertencer ao workspace; caso contrário, nada é alterado e a requisição retorna 404 com os IDs ausentes em missing. Arquivar e desarquivar disparam audience.updated; excluir dispara audience.deleted e remove os inscritos das listas, como Excluir uma lista de contatos. Consulte Arquivar uma lista.

Parâmetros do corpo

actionstringobrigatório

archive, unarchive ou delete.

idsstring[]obrigatório

IDs de listas de contatos, de 1 a 100.

Retorno

objectstring

Sempre audience_bulk.

actionstring

A ação que você enviou.

processedinteger

Quantas listas foram encontradas.

changedinteger

Quantas foram de fato alteradas. Arquivar uma lista que já está arquivada não conta.

idsstring[]

Os IDs que você enviou.

POST/audiences/bulk

JavaScript

const response = await fetch('https://api.emailit.com/v2/audiences/bulk', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer your_api_key',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    action: 'archive',
    ids: ['aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2', 'aud_4KOlh9t2uw5od4qypqCtyrZyDq2']
  })
});

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

Terminal

curl -X POST https://api.emailit.com/v2/audiences/bulk \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"action": "archive", "ids": ["aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2", "aud_4KOlh9t2uw5od4qypqCtyrZyDq2"]}'

JSON

{
  "object": "audience_bulk",
  "action": "archive",
  "processed": 2,
  "changed": 2,
  "ids": ["aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2", "aud_4KOlh9t2uw5od4qypqCtyrZyDq2"]
}

JSON

{
  "error": "One or more audiences were not found",
  "missing": ["aud_4KOlh9t2uw5od4qypqCtyrZyDq2"]
}

Excluir uma lista de contatos

Exclui permanentemente uma lista de contatos e remove todas as pessoas dela.

DELETE/audiences/{id}

Requer uma chave de API com escopo full. As participações de inscritos na lista são excluídas com ela, mas os contatos continuam no seu workspace e nas outras listas deles. A URL de inscrição hospedada da lista para de funcionar. Dispara um evento audience.deleted. Nenhum evento subscriber.deleted é enviado para as participações removidas.

Parâmetros de caminho

idstringobrigatório

O ID da lista de contatos ou o nome dela.

Retorno

objectstring

Sempre audience.

idstring

O ID da lista de contatos excluída.

namestring

O nome da lista de contatos.

deletedboolean

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