Inscritos
Adicione, atualize e remova os inscritos de uma lista de contatos.
Adicionar um inscrito
Adiciona um contato a uma lista de contatos pelo endereço de e-mail.
/audiences/{audience_id}/subscribersRequer 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órioaud_…) ou o nome dela.Parâmetros do corpo
emailstringobrigatóriofirst_namestringlast_namestringcustom_fieldsobjectValores 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.
{
"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"
}{
"error": "Audience not found"
}{
"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"
}
}{
"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.
/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órioaud_…) ou o nome dela.idstringobrigatóriosub_…) ou o endereço de e-mail do contato, codificado para URL.Retorno
Retorna o objeto de inscrito.
objectstringsubscriber.idstringaudience_idstringcontact_idstringemailstringfirst_namestring | nulllast_namestring | nullcustom_fieldsobject | nullsubscribedbooleantrue se o contato estiver inscrito nesta lista, false se tiver se descadastrado.subscribed_atstring | nullunsubscribed_atstring | nullnull.created_atstringupdated_atstring{
"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"
}{
"error": "Subscriber not found"
}Atualizar um inscrito
Altera o status de um inscrito na lista de contatos ou os dados do contato dele.
/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órioaud_…) ou o nome dela.idstringobrigatóriosub_…) ou o endereço de e-mail do contato, codificado para URL.Parâmetros do corpo
subscribedbooleanfalse para descadastrar o contato desta lista, true para inscrevê-lo de novo. O inscrito continua na lista nos dois casos.emailstringfirst_namestringlast_namestringcustom_fieldsobjectRetorno
Retorna o objeto de inscrito atualizado. Uma requisição sem nenhum desses campos retorna 400.
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}'{
"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"
}{
"error": "No valid fields provided for update. Provide at least one of: email, first_name, last_name, custom_fields, subscribed"
}{
"error": "Subscriber not found"
}Listar inscritos
Retorna uma página de inscritos de uma lista de contatos, dos mais recentes para os mais antigos.
/audiences/{audience_id}/subscribersRequer 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órioaud_…) ou o nome dela.Parâmetros de consulta
pageintegerpadrão: 1limitintegerpadrão: 25per_page também funciona.subscribedstringtrue para apenas os contatos inscritos, false para apenas os descadastrados.searchstringmatchstringpadrão: allall ou or. Como os filtros abaixo se combinam.orderstringdirectionstringasc 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[]next_page_urlstring | nullnull. Mantém subscribed, mas não os seus outros filtros. Consulte Paginação.previous_page_urlstring | nullnull.usageobjectused (inscritos na lista), limit (o máximo que o seu plano permite por lista, ou null) e plan.curl -G https://api.emailit.com/v2/audiences/aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2/subscribers \
-H "Authorization: Bearer $EMAILIT_API_KEY" \
-d subscribed=true \
-d limit=100{
"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"
}
}{
"error": "Audience not found"
}Excluir um inscrito
Remove um contato de uma lista de contatos.
/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órioaud_…) ou o nome dela.idstringobrigatóriosub_…) ou o endereço de e-mail do contato, codificado para URL.Retorno
objectstringsubscriber.idstringaudience_idstringcontact_idstringemailstringdeletedbooleantrue.{
"object": "subscriber",
"id": "sub_4KECYl5AwXEy8ezswYRhuddttxo",
"audience_id": "aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2",
"contact_id": "con_4K9kQdrXth7am0TPKvPrR5yd2oo",
"email": "ada@example.com",
"deleted": true
}{
"error": "Subscriber not found"
}