Pular para o conteúdo
Docs

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

URL basehttps://api.emailit.com/v2AutenticaçãoErrosLimites de requisições

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.

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.

Retorno

Retorna 201 com o objeto de inscrito, ou 200 quando um contato descadastrado foi inscrito de novo.

POST/audiences/{audience_id}/subscribers
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"
}

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

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

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.
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
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.
next_page_urlstring | null
Caminho da próxima página, ou null. Mantém subscribed, 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
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,
      "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",
      "created_at": "2026-09-28T07:55:02.000000Z",
      "updated_at": "2026-09-30T18:11:40.000000Z"
    }
  ],
  "next_page_url": null,
  "previous_page_url": null,
  "usage": {
    "used": 2,
    "limit": 50000,
    "plan": "pro"
  }
}

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

Esta página foi útil?

Obrigado pelo feedback.

Obrigado, lemos todas as mensagens.