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

Retorno

Retorna 201 com a nova lista de contatos:

objectstring

Sempre audience.

idstring

O ID da lista de contatos.

namestring

O nome da lista de contatos.

tokenstring

O token público da URL de inscrição hospedada da lista.

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",
  "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 a contagem de inscritos 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 público da URL de inscrição hospedada da lista. Trate-o como público: qualquer pessoa que o tenha pode se inscrever na lista.

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.

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

Atualizar uma lista de contatos

Renomeia uma lista de contatos.

POST/audiences/{id}

Requer uma chave de API com escopo full. 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

namestringobrigatório

O novo nome. Deve ser único no workspace.

Retorno

Retorna a lista de contatos com object, id, name, token, subscribers_count, created_at e updated_at. Nesta resposta, subscribers_count é sempre 0; use Obter uma lista de contatos para a contagem real.

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 contatos

Retorna uma página de listas de contatos, das mais recentes para as mais antigas.

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.

matchstringpadrão: all

all ou or. Como os filtros abaixo se combinam.

orderstring

name 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
`created_at`	date

Retorno

dataobject[]

As listas de contatos desta página, cada uma com object, id, name, subscribers_count, usage, created_at e updated_at. Consulte Obter uma lista de contatos.

total_recordsinteger

O número de listas de contatos no workspace.

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

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