# Contatos API

> Gerencie perfis de contato e campos personalizados, em massa ou um por vez.

URL base: `https://api.emailit.com/v2`. Autentique-se com `Authorization: Bearer <API key>`.

## Criar um contato — POST /contacts

> Crie um contato com endereço de e-mail, nomes e campos personalizados e, se quiser, inscreva-o em uma ou mais listas de contatos de uma vez.

# Criar um contato

Cria um contato e, opcionalmente, inscreve-o em listas de contatos.

`POST /contacts`

Requer uma chave de API com escopo `full`. Os endereços de e-mail são únicos por workspace e armazenados em minúsculas; criar um contato que já existe retorna `409` com o contato existente em `existing`. Dispara `contact.created` e `subscriber.created` para cada lista de contatos. Consulte [Contatos](/pt/docs/contacts/).

## Parâmetros do corpo

- `email` (string, obrigatório): O endereço de e-mail do contato.

- `first_name` (string): O nome.

- `last_name` (string): O sobrenome.

- `custom_fields` (object): Valores por chave de [campo personalizado](/pt/docs/contacts/custom-fields/), como `{"company": "Analytical Engines"}`. Os valores de campos de data devem estar no formato `YYYY-MM-DD`. Chaves que não correspondem a um campo personalizado são armazenadas como estão.

- `audiences` (string[]): IDs das listas de contatos (`aud_…`) em que o contato será inscrito. IDs que não existem no workspace são ignorados.

- `unsubscribed` (boolean): `true` para criar o contato como descadastrado. As campanhas ignoram contatos descadastrados, e a participação deles em listas começa como descadastrada.

## Retorno

Retorna `201` com o objeto de contato. Aqui, `audiences` lista cada lista de contatos com `id`, `name` e o status `subscribed`. Consulte [Obter um contato](/pt/docs/api-reference/contacts/get/) para ver todos os campos.

Retorna `422` com `usage` quando uma lista de contatos está no limite de inscritos do seu plano. Nesse caso, nenhum contato é criado.

**Requisição** `POST /contacts`

**Node.js**

```javascript
import { Emailit } from '@emailit/node';
const emailit = new Emailit('your_api_key');

const contact = await emailit.contacts.create({
  email: 'ada@example.com',
  first_name: 'Ada',
  last_name: 'Lovelace',
});
```

**Python**

```python
from emailit import EmailitClient
client = EmailitClient("your_api_key")

contact = client.contacts.create({
  "email": "ada@example.com",
  "first_name": "Ada",
  "last_name": "Lovelace",
})
```

**PHP**

```php
$emailit = Emailit::client('your_api_key');

$contact = $emailit->contacts()->create([
  'email' => 'ada@example.com',
  'first_name' => 'Ada',
  'last_name' => 'Lovelace',
]);
```

**Ruby**

```ruby
require "emailit"
client = Emailit::EmailitClient.new("your_api_key")

contact = client.contacts.create(
  email: "ada@example.com",
  first_name: "Ada",
  last_name: "Lovelace"
)
```

**Go**

```go
import "github.com/emailit/emailit-go/v2"
client := emailit.NewClient("your_api_key")

contact, err := client.Contacts.Create(&emailit.CreateContactRequest{
  Email:     "ada@example.com",
  FirstName: "Ada",
  LastName:  "Lovelace",
})
```

**Rust**

```rust
use emailit::Emailit;

let emailit = Emailit::new("your_api_key");

let contact = emailit.contacts.create(
  emailit::types::CreateContactParams::new("ada@example.com")
    .with_first_name("Ada")
    .with_last_name("Lovelace")
).await?;
```

**Java**

```java
import com.emailit.*;
import com.emailit.params.*;

EmailitClient emailit = new EmailitClient("your_api_key");

EmailitObject contact = emailit.contacts().create(
  ContactCreateParams.builder()
    .setEmail("ada@example.com")
    .setFirstName("Ada")
    .setLastName("Lovelace")
    .build()
);
```

**.NET**

```csharp
using Emailit;

var emailit = new EmailitClient("your_api_key");

var contact = emailit.Contacts.Create(new ContactCreateOptions {
  Email = "ada@example.com",
  FirstName = "Ada",
  LastName = "Lovelace",
});
```

**Laravel**

```php
use Emailit\Laravel\Facades\Emailit;

$contact = Emailit::contacts()->create([
  'email' => 'ada@example.com',
  'first_name' => 'Ada',
  'last_name' => 'Lovelace',
]);
```

**cURL**

```bash
curl -X POST https://api.emailit.com/v2/contacts \
  -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", "plan": "pro" },
    "audiences": ["aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2"]
  }'
```

**201**

```json
{
  "object": "contact",
  "id": "con_4K9kQdrXth7am0TPKvPrR5yd2oo",
  "email": "ada@example.com",
  "first_name": "Ada",
  "last_name": "Lovelace",
  "custom_fields": {
    "company": "Analytical Engines",
    "plan": "pro"
  },
  "unsubscribed": false,
  "audiences": [
    {
      "id": "aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2",
      "name": "Newsletter",
      "subscribed": true
    }
  ],
  "created_at": "2026-10-01T10:20:31.704113Z",
  "updated_at": "2026-10-01T10:20:31.704113Z"
}
```

**400**

```json
{
  "error": "Custom field \"Birthday\" must be a date in YYYY-MM-DD format"
}
```

**409**

```json
{
  "error": "Contact with this email already exists",
  "existing": {
    "object": "contact",
    "id": "con_4K9kQdrXth7am0TPKvPrR5yd2oo",
    "email": "ada@example.com",
    "first_name": "Ada",
    "last_name": "Lovelace",
    "custom_fields": {
      "company": "Analytical Engines",
      "plan": "pro"
    },
    "unsubscribed": false,
    "audiences": [
      {
        "id": "aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2",
        "name": "Newsletter",
        "subscribed": true
      }
    ],
    "created_at": "2026-10-01T10:20:31.704113Z",
    "updated_at": "2026-10-01T10:20:31.704113Z"
  }
}
```

**422**

```json
{
  "error": "Pro includes 50,000 subscribers per audience.",
  "usage": {
    "used": 50000,
    "limit": 50000,
    "plan": "pro"
  }
}
```

---
Fonte: https://emailit.com/pt/docs/api-reference/contacts/create/

## Obter um contato — GET /contacts/{id}

> Obtenha um contato pelo ID ou pelo endereço de e-mail, com os campos personalizados e toda a participação dele em listas de contatos, incluindo as datas de inscrição.

# Obter um contato

Obtém um contato com os campos personalizados e a participação dele em listas de contatos.

`GET /contacts/{id}`

Requer uma chave de API com escopo `full`.

## Parâmetros de caminho

- `id` (string, obrigatório): O ID do contato (`con_…`) ou o endereço de e-mail do contato, codificado para URL.

## Retorno

Retorna o objeto de contato.

- `object` (string): Sempre `contact`.

- `id` (string): O ID do contato.

- `email` (string): O endereço de e-mail, em minúsculas.

- `first_name` (string | null): O nome.

- `last_name` (string | null): O sobrenome.

- `custom_fields` (object): Valores de campos personalizados por chave. `{}` quando não há nenhum.

- `unsubscribed` (boolean): `true` se o contato se descadastrou de todas as campanhas.

- `audiences` (object[]): As listas de contatos de que o contato participa, cada uma com `id`, `name` e um objeto `subscriber`: `id` (`sub_…`), `subscribed`, `subscribed_at`, `unsubscribed_at`, `created_at` e `updated_at`.

- `created_at` (string): Quando o contato foi criado.

- `updated_at` (string): Quando o contato foi alterado pela última vez.

**Requisição** `GET /contacts/{id}`

**Node.js**

```javascript
import { Emailit } from '@emailit/node';
const emailit = new Emailit('your_api_key');

const contact = await emailit.contacts.get('con_4K9kQdrXth7am0TPKvPrR5yd2oo');
```

**Python**

```python
from emailit import EmailitClient
client = EmailitClient("your_api_key")

contact = client.contacts.get("con_4K9kQdrXth7am0TPKvPrR5yd2oo")
```

**PHP**

```php
$emailit = Emailit::client('your_api_key');

$contact = $emailit->contacts()->get('con_4K9kQdrXth7am0TPKvPrR5yd2oo');
```

**Ruby**

```ruby
require "emailit"
client = Emailit::EmailitClient.new("your_api_key")

contact = client.contacts.get("con_4K9kQdrXth7am0TPKvPrR5yd2oo")
```

**Go**

```go
import "github.com/emailit/emailit-go/v2"
client := emailit.NewClient("your_api_key")

contact, err := client.Contacts.Get("con_4K9kQdrXth7am0TPKvPrR5yd2oo")
```

**Rust**

```rust
use emailit::Emailit;

let emailit = Emailit::new("your_api_key");

let contact = emailit.contacts.get("con_4K9kQdrXth7am0TPKvPrR5yd2oo").await?;
```

**Java**

```java
import com.emailit.*;

EmailitClient emailit = new EmailitClient("your_api_key");

EmailitObject contact = emailit.contacts().get("con_4K9kQdrXth7am0TPKvPrR5yd2oo");
```

**.NET**

```csharp
using Emailit;

var emailit = new EmailitClient("your_api_key");

var contact = emailit.Contacts.Get("con_4K9kQdrXth7am0TPKvPrR5yd2oo");
```

**Laravel**

```php
use Emailit\Laravel\Facades\Emailit;

$contact = Emailit::contacts()->get('con_4K9kQdrXth7am0TPKvPrR5yd2oo');
```

**cURL**

```bash
curl https://api.emailit.com/v2/contacts/con_4K9kQdrXth7am0TPKvPrR5yd2oo \
  -H "Authorization: Bearer $EMAILIT_API_KEY"
```

**200**

```json
{
  "object": "contact",
  "id": "con_4K9kQdrXth7am0TPKvPrR5yd2oo",
  "email": "ada@example.com",
  "first_name": "Ada",
  "last_name": "Lovelace",
  "custom_fields": {
    "company": "Analytical Engines",
    "plan": "pro"
  },
  "unsubscribed": false,
  "audiences": [
    {
      "id": "aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2",
      "name": "Newsletter",
      "subscriber": {
        "id": "sub_4KECYl5AwXEy8ezswYRhuddttxo",
        "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"
      }
    }
  ],
  "created_at": "2026-10-01T10:20:31.000000Z",
  "updated_at": "2026-10-01T10:20:31.000000Z"
}
```

**404**

```json
{
  "error": "Contact not found"
}
```

---
Fonte: https://emailit.com/pt/docs/api-reference/contacts/get/

## Atualizar um contato — POST /contacts/{id}

> Altere o endereço de e-mail, os nomes, os campos personalizados ou o status de descadastro de um contato, ou substitua as listas de contatos de que ele participa.

# Atualizar um contato

Atualiza um contato. Só mudam os campos que você enviar.

`POST /contacts/{id}`

Requer uma chave de API com escopo `full`. Dispara `contact.updated`, com os valores anteriores dos campos alterados em `previous`. Alterar `audiences` também dispara `subscriber.created` e `subscriber.deleted` para as participações em listas que forem adicionadas e removidas.

## Parâmetros de caminho

- `id` (string, obrigatório): O ID do contato (`con_…`) ou o endereço de e-mail do contato, codificado para URL.

## Parâmetros do corpo

- `email` (string): Um novo endereço de e-mail. Não pode pertencer a outro contato.

- `first_name` (string): O nome.

- `last_name` (string): O sobrenome.

- `custom_fields` (object): Valores de campos personalizados por chave. Substitui todos os campos personalizados do contato, então inclua os que você quer manter.

- `unsubscribed` (boolean): `true` para descadastrar o contato de todas as campanhas, `false` para reinscrevê-lo. As participações existentes em listas mantêm o próprio status.

- `audiences` (string[]): A lista completa de IDs das listas de contatos de que o contato deve participar. O contato é adicionado às listas em que ainda não está e removido das listas que não estão na sua relação. Envie `[]` para removê-lo de todas as listas. Para adicionar ou remover uma lista sem relacionar todas, use [Adicionar um inscrito](/pt/docs/api-reference/audiences/subscribers/add/) ou [Excluir um inscrito](/pt/docs/api-reference/audiences/subscribers/delete/).

## Retorno

Retorna o contato atualizado no mesmo formato de [Obter um contato](/pt/docs/api-reference/contacts/get/). Uma requisição sem nenhum desses campos retorna `400`.

**Requisição** `POST /contacts/{id}`

**Node.js**

```javascript
import { Emailit } from '@emailit/node';
const emailit = new Emailit('your_api_key');

const contact = await emailit.contacts.update('con_4K9kQdrXth7am0TPKvPrR5yd2oo', {
  first_name: 'Augusta',
});
```

**Python**

```python
from emailit import EmailitClient
client = EmailitClient("your_api_key")

contact = client.contacts.update("con_4K9kQdrXth7am0TPKvPrR5yd2oo", {
  "first_name": "Augusta",
})
```

**PHP**

```php
$emailit = Emailit::client('your_api_key');

$contact = $emailit->contacts()->update('con_4K9kQdrXth7am0TPKvPrR5yd2oo', [
  'first_name' => 'Augusta',
]);
```

**Ruby**

```ruby
require "emailit"
client = Emailit::EmailitClient.new("your_api_key")

contact = client.contacts.update("con_4K9kQdrXth7am0TPKvPrR5yd2oo",
  first_name: "Augusta"
)
```

**Go**

```go
import "github.com/emailit/emailit-go/v2"
client := emailit.NewClient("your_api_key")

contact, err := client.Contacts.Update("con_4K9kQdrXth7am0TPKvPrR5yd2oo", &emailit.UpdateContactRequest{
  FirstName: "Augusta",
})
```

**Rust**

```rust
use emailit::Emailit;

let emailit = Emailit::new("your_api_key");

let contact = emailit.contacts.update("con_4K9kQdrXth7am0TPKvPrR5yd2oo",
  emailit::types::UpdateContactParams {
    first_name: Some("Augusta".into()),
    ..Default::default()
  }
).await?;
```

**Java**

```java
import com.emailit.*;
import com.emailit.params.*;

EmailitClient emailit = new EmailitClient("your_api_key");

EmailitObject contact = emailit.contacts().update("con_4K9kQdrXth7am0TPKvPrR5yd2oo", 
  ContactUpdateParams.builder()
    .setFirstName("Augusta")
    .build()
);
```

**.NET**

```csharp
using Emailit;

var emailit = new EmailitClient("your_api_key");

var contact = emailit.Contacts.Update("con_4K9kQdrXth7am0TPKvPrR5yd2oo", new ContactUpdateOptions {
  FirstName = "Augusta",
});
```

**Laravel**

```php
use Emailit\Laravel\Facades\Emailit;

$contact = Emailit::contacts()->update('con_4K9kQdrXth7am0TPKvPrR5yd2oo', [
  'first_name' => 'Augusta',
]);
```

**cURL**

```bash
curl -X POST https://api.emailit.com/v2/contacts/con_4K9kQdrXth7am0TPKvPrR5yd2oo \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"first_name": "Augusta"}'
```

**cURL**

```bash
curl -X POST https://api.emailit.com/v2/contacts/ada%40example.com \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "custom_fields": { "company": "Analytical Engines", "plan": "business" },
    "audiences": ["aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2", "aud_4KOlh9t2uw5od4qypqCtyrZyDq2"]
  }'
```

**200**

```json
{
  "object": "contact",
  "id": "con_4K9kQdrXth7am0TPKvPrR5yd2oo",
  "email": "ada@example.com",
  "first_name": "Augusta",
  "last_name": "Lovelace",
  "custom_fields": {
    "company": "Analytical Engines",
    "plan": "pro"
  },
  "unsubscribed": false,
  "audiences": [
    {
      "id": "aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2",
      "name": "Newsletter",
      "subscriber": {
        "id": "sub_4KECYl5AwXEy8ezswYRhuddttxo",
        "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"
      }
    }
  ],
  "created_at": "2026-10-01T10:20:31.000000Z",
  "updated_at": "2026-10-02T09:03:17.000000Z"
}
```

**400**

```json
{
  "error": "No valid fields provided for update. Provide at least one of: email, first_name, last_name, custom_fields, unsubscribed, audiences"
}
```

**404**

```json
{
  "error": "Contact not found"
}
```

**409**

```json
{
  "error": "Another contact with this email already exists"
}
```

---
Fonte: https://emailit.com/pt/docs/api-reference/contacts/update/

## Listar contatos — GET /contacts

> Liste os contatos de um workspace, dos mais recentes para os mais antigos, filtrados por lista de contatos, status de inscrição, campos personalizados ou qualquer campo do contato.

# Listar contatos

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

`GET /contacts`

Requer uma chave de API com escopo `full`. Use os mesmos parâmetros com [Exportar contatos](/pt/docs/api-reference/contacts/export/) para baixar todas as correspondências como arquivo.

## Parâmetros de consulta

- `page` (integer): A página a retornar.

- `limit` (integer): Contatos por página, de 1 a 100.

- `search` (string): Busca sem diferenciar maiúsculas de minúsculas no endereço de e-mail, no nome ou no sobrenome. `q` também funciona.

- `audience_id` (string): Apenas os contatos desta lista de contatos (`aud_…`).

- `unsubscribed` (boolean): `true` ou `false`. Apenas os contatos com este status de descadastro.

- `sort` (string): `email`, `first_name`, `last_name`, `name`, `audiences`, `created_at` ou `updated_at`.

- `order` (string): `asc` ou `desc`. Neste endpoint, `order` é a direção da ordenação, não a chave de ordenação.

- `match` (string): `all` ou `or`. Como os filtros abaixo se combinam.

## Filtros

Adicione filtros no formato `key.condition=value`, por exemplo `email.ends_with=@acme.com` ou `custom_fields.plan.exact=pro`. Consulte [Filtragem](/pt/docs/api-reference/filtering/).

| Chave | Tipo | Observações |
| --- | --- | --- |
| `email` | string | |
| `first_name` | string | |
| `last_name` | string | |
| `name` | string | Nome e sobrenome unidos por um espaço. |
| `audiences` | string | O nome da lista do contato que vem primeiro em ordem alfabética. |
| `unsubscribed` | boolean | |
| `created_at` | date | |
| `updated_at` | date | |
| `audience_id` | string | Apenas `exact` e `not_exact`. O valor é um ID de lista de contatos. |
| `custom_fields.<key>` | string | Substitua `<key>` pela chave de um campo personalizado. Os valores são comparados como texto. |

Os parâmetros antigos `filter[audience_id]`, `filter[unsubscribed]` e `filter[custom_fields][<key>]` continuam funcionando.

## Retorno

- `data` (object[]): Os contatos desta página, cada um com `audiences` no formato `id`, `name` e `subscribed`. Consulte [Obter um contato](/pt/docs/api-reference/contacts/get/).

- `total_records` (integer): O número de contatos correspondentes, somando todas as páginas.

- `next_page_url` (string | null): Caminho da próxima página com os seus filtros, ou `null`. Consulte [Paginação](/pt/docs/api-reference/pagination/).

- `previous_page_url` (string | null): Caminho da página anterior, ou `null`.

**Requisição** `GET /contacts`

**Node.js**

```javascript
import { Emailit } from '@emailit/node';
const emailit = new Emailit('your_api_key');

const contacts = await emailit.contacts.list();
```

**Python**

```python
from emailit import EmailitClient
client = EmailitClient("your_api_key")

contacts = client.contacts.list()
```

**PHP**

```php
$emailit = Emailit::client('your_api_key');

$contacts = $emailit->contacts()->list();
```

**Ruby**

```ruby
require "emailit"
client = Emailit::EmailitClient.new("your_api_key")

contacts = client.contacts.list
```

**Go**

```go
import "github.com/emailit/emailit-go/v2"
client := emailit.NewClient("your_api_key")

contacts, err := client.Contacts.List(nil)
```

**Rust**

```rust
use emailit::Emailit;

let emailit = Emailit::new("your_api_key");

let contacts = emailit.contacts.list(None).await?;
```

**Java**

```java
import com.emailit.*;

EmailitClient emailit = new EmailitClient("your_api_key");

EmailitObject contacts = emailit.contacts().list();
```

**.NET**

```csharp
using Emailit;

var emailit = new EmailitClient("your_api_key");

var contacts = emailit.Contacts.List();
```

**Laravel**

```php
use Emailit\Laravel\Facades\Emailit;

$contacts = Emailit::contacts()->list();
```

**cURL**

```bash
curl https://api.emailit.com/v2/contacts \
  -H "Authorization: Bearer $EMAILIT_API_KEY"
```

**cURL**

```bash
curl -G https://api.emailit.com/v2/contacts \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  --data-urlencode "audience_id=aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2" \
  --data-urlencode "custom_fields.plan.exact=pro" \
  --data-urlencode "sort=email" \
  --data-urlencode "order=asc" \
  --data-urlencode "limit=100"
```

**200**

```json
{
  "data": [
    {
      "object": "contact",
      "id": "con_4K9kQdrXth7am0TPKvPrR5yd2oo",
      "email": "ada@example.com",
      "first_name": "Ada",
      "last_name": "Lovelace",
      "custom_fields": {
        "company": "Analytical Engines",
        "plan": "pro"
      },
      "unsubscribed": false,
      "audiences": [
        {
          "id": "aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2",
          "name": "Newsletter",
          "subscribed": true
        }
      ],
      "created_at": "2026-10-01T10:20:31.704113Z",
      "updated_at": "2026-10-01T10:20:31.704113Z"
    },
    {
      "object": "contact",
      "id": "con_4KiXIs4xLTcJIAHnKJaLcnMZYh7",
      "email": "grace@example.com",
      "first_name": "Grace",
      "last_name": "Hopper",
      "custom_fields": {},
      "unsubscribed": true,
      "audiences": [],
      "created_at": "2026-09-28T07:55:02.118342Z",
      "updated_at": "2026-09-30T18:11:40.902215Z"
    }
  ],
  "total_records": 2,
  "next_page_url": null,
  "previous_page_url": null
}
```

---
Fonte: https://emailit.com/pt/docs/api-reference/contacts/list/

## Atualizar contatos em massa — POST /contacts/bulk

> Aplique uma ação a até 100 contatos de uma vez: exclua-os, adicione-os a uma lista de contatos ou remova-os dela, descadastre-os ou reinscreva-os.

# Atualizar contatos em massa

Executa uma ação em até 100 contatos em uma única requisição.

`POST /contacts/bulk`

Requer uma chave de API com escopo `full`. Todos os IDs devem pertencer a contatos do workspace; caso contrário, nada é alterado e a resposta lista os IDs ausentes em `missing`. Cada contato dispara os mesmos eventos que os endpoints de um único contato. Se a lista de contatos atingir o limite de inscritos do seu plano durante `add_to_audience`, a requisição para com `422`, e os contatos processados até então continuam adicionados.

| Ação | O que faz |
| --- | --- |
| `delete` | Exclui os contatos e a participação deles em listas, como [Excluir um contato](/pt/docs/api-reference/contacts/delete/). |
| `add_to_audience` | Adiciona os contatos a `audience_id`. Os contatos que já estão na lista ficam como estão. |
| `remove_from_audience` | Remove os contatos de `audience_id`. |
| `unsubscribe` | Define `unsubscribed` como `true`, para que as campanhas ignorem os contatos. |
| `resubscribe` | Define `unsubscribed` como `false`. |

## Parâmetros do corpo

- `action` (string, obrigatório): `delete`, `add_to_audience`, `remove_from_audience`, `unsubscribe` ou `resubscribe`.

- `ids` (string[], obrigatório): IDs de contatos (`con_…`), de 1 a 100. Endereços de e-mail não são aceitos aqui. IDs duplicados são ignorados.

- `audience_id` (string): O ID da lista de contatos. Obrigatório para `add_to_audience` e `remove_from_audience`.

## Retorno

- `object` (string): Sempre `contact_bulk`.

- `action` (string): A ação executada.

- `processed` (integer): Quantos contatos foram processados.

- `ids` (string[]): Os IDs dos contatos processados.

**Requisição** `POST /contacts/bulk`

**Node.js**

```javascript
const response = await fetch('https://api.emailit.com/v2/contacts/bulk', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer your_api_key',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({"action": "add_to_audience", "ids": ["con_4K9kQdrXth7am0TPKvPrR5yd2oo", "con_4KiXIs4xLTcJIAHnKJaLcnMZYh7"], "audience_id": "aud_4KOlh9t2uw5od4qypqCtyrZyDq2"}),
});
const result = await response.json();
```

**Python**

```python
import requests

response = requests.post(
  "https://api.emailit.com/v2/contacts/bulk",
  headers={"Authorization": "Bearer your_api_key"},
  json={"action": "add_to_audience", "ids": ["con_4K9kQdrXth7am0TPKvPrR5yd2oo", "con_4KiXIs4xLTcJIAHnKJaLcnMZYh7"], "audience_id": "aud_4KOlh9t2uw5od4qypqCtyrZyDq2"}
)
result = response.json()
```

**PHP**

```php
$ch = curl_init('https://api.emailit.com/v2/contacts/bulk');
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    'Authorization: Bearer your_api_key',
    'Content-Type: application/json',
  ],
  CURLOPT_POSTFIELDS => json_encode(['action' => 'add_to_audience', 'ids' => ['con_4K9kQdrXth7am0TPKvPrR5yd2oo', 'con_4KiXIs4xLTcJIAHnKJaLcnMZYh7'], 'audience_id' => 'aud_4KOlh9t2uw5od4qypqCtyrZyDq2']),
]);
$result = json_decode(curl_exec($ch), true);
curl_close($ch);
```

**Ruby**

```ruby
require "net/http"
require "json"

uri = URI("https://api.emailit.com/v2/contacts/bulk")
req = Net::HTTP::Post.new(uri)
req["Authorization"] = "Bearer your_api_key"
req["Content-Type"] = "application/json"
req.body = { action: "add_to_audience", ids: ["con_4K9kQdrXth7am0TPKvPrR5yd2oo", "con_4KiXIs4xLTcJIAHnKJaLcnMZYh7"], audience_id: "aud_4KOlh9t2uw5od4qypqCtyrZyDq2" }.to_json
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
result = JSON.parse(http.request(req).body)
```

**Go**

```go
payload := strings.NewReader(`{"action": "add_to_audience", "ids": ["con_4K9kQdrXth7am0TPKvPrR5yd2oo", "con_4KiXIs4xLTcJIAHnKJaLcnMZYh7"], "audience_id": "aud_4KOlh9t2uw5od4qypqCtyrZyDq2"}`)
req, _ := http.NewRequest("POST", "https://api.emailit.com/v2/contacts/bulk", payload)
req.Header.Set("Authorization", "Bearer your_api_key")
req.Header.Set("Content-Type", "application/json")

resp, err := http.DefaultClient.Do(req)
if err != nil {
  return err
}
defer resp.Body.Close()
```

**Rust**

```rust
let response = reqwest::Client::new()
    .post("https://api.emailit.com/v2/contacts/bulk")
    .bearer_auth("your_api_key")
    .json(&serde_json::json!({"action": "add_to_audience", "ids": ["con_4K9kQdrXth7am0TPKvPrR5yd2oo", "con_4KiXIs4xLTcJIAHnKJaLcnMZYh7"], "audience_id": "aud_4KOlh9t2uw5od4qypqCtyrZyDq2"}))
    .send()
    .await?;
```

**Java**

```java
import java.net.http.*;
import java.net.URI;

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
  .uri(URI.create("https://api.emailit.com/v2/contacts/bulk"))
  .header("Authorization", "Bearer your_api_key")
  .header("Content-Type", "application/json")
  .POST(HttpRequest.BodyPublishers.ofString("{\"action\": \"add_to_audience\", \"ids\": [\"con_4K9kQdrXth7am0TPKvPrR5yd2oo\", \"con_4KiXIs4xLTcJIAHnKJaLcnMZYh7\"], \"audience_id\": \"aud_4KOlh9t2uw5od4qypqCtyrZyDq2\"}"))
  .build();
HttpResponse<String> response = client.send(request,
  HttpResponse.BodyHandlers.ofString());
```

**.NET**

```csharp
using System.Net.Http.Headers;
using System.Text;

var http = new HttpClient();
http.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", "your_api_key");

var content = new StringContent(@"{""action"": ""add_to_audience"", ""ids"": [""con_4K9kQdrXth7am0TPKvPrR5yd2oo"", ""con_4KiXIs4xLTcJIAHnKJaLcnMZYh7""], ""audience_id"": ""aud_4KOlh9t2uw5od4qypqCtyrZyDq2""}", Encoding.UTF8, "application/json");
var response = await http.PostAsync("https://api.emailit.com/v2/contacts/bulk", content);
```

**Laravel**

```php
use Illuminate\Support\Facades\Http;

$result = Http::withToken('your_api_key')
  ->post('https://api.emailit.com/v2/contacts/bulk', ['action' => 'add_to_audience', 'ids' => ['con_4K9kQdrXth7am0TPKvPrR5yd2oo', 'con_4KiXIs4xLTcJIAHnKJaLcnMZYh7'], 'audience_id' => 'aud_4KOlh9t2uw5od4qypqCtyrZyDq2'])
  ->json();
```

**cURL**

```bash
curl -X POST https://api.emailit.com/v2/contacts/bulk \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"action": "add_to_audience", "ids": ["con_4K9kQdrXth7am0TPKvPrR5yd2oo", "con_4KiXIs4xLTcJIAHnKJaLcnMZYh7"], "audience_id": "aud_4KOlh9t2uw5od4qypqCtyrZyDq2"}'
```

**200**

```json
{
  "object": "contact_bulk",
  "action": "add_to_audience",
  "processed": 2,
  "ids": ["con_4K9kQdrXth7am0TPKvPrR5yd2oo", "con_4KiXIs4xLTcJIAHnKJaLcnMZYh7"]
}
```

**400**

```json
{
  "error": "A maximum of 100 contacts can be updated per request"
}
```

**404**

```json
{
  "error": "One or more contacts were not found",
  "missing": ["con_4K3pZc1Q9nWm2LrT8vYb5Hd0XaE"]
}
```

**422**

```json
{
  "error": "Pro includes 50,000 subscribers per audience.",
  "usage": {
    "used": 50000,
    "limit": 50000,
    "plan": "pro"
  }
}
```

---
Fonte: https://emailit.com/pt/docs/api-reference/contacts/bulk/

## Exportar contatos — GET /contacts/export

> Baixe os contatos que correspondem aos seus filtros como arquivo CSV ou Excel, com as listas de contatos e os campos personalizados deles. Até 10.000 contatos.

# Exportar contatos

Baixa os contatos correspondentes como arquivo CSV ou XLSX.

`GET /contacts/export`

Requer uma chave de API com escopo `full`. Aceita os mesmos parâmetros de busca, filtro e ordenação que [Listar contatos](/pt/docs/api-reference/contacts/list/), passados na query string, sem paginação. `POST /contacts/export` funciona da mesma forma. Uma exportação pode incluir até 10.000 contatos; se houver mais correspondências, a requisição retorna `422`, então restrinja os filtros.

## Parâmetros de consulta

- `format` (string): `csv` ou `xlsx`.

- `search, audience_id, unsubscribed, sort, order, match, key.condition` (string): Os mesmos parâmetros de [Listar contatos](/pt/docs/api-reference/contacts/list/).

## Retorno

Retorna o arquivo como anexo: `contacts.csv` (`text/csv; charset=utf-8`) ou `contacts.xlsx`. Cada linha é um contato, com estas colunas:

| Coluna | Contém |
| --- | --- |
| `email` | O endereço de e-mail. |
| `first_name`, `last_name` | Os nomes. |
| `unsubscribed` | `true` ou `false`. |
| `audiences` | Os nomes das listas de contatos do contato, separados por `; `. |
| Uma coluna por campo personalizado | O valor de cada campo personalizado definido no workspace, com a chave dele como nome. Listas de valores são unidas com `;`. |
| `created_at`, `updated_at` | Timestamps ISO 8601. |

**Requisição** `GET /contacts/export`

**Node.js**

```javascript
import { writeFile } from 'node:fs/promises';

const response = await fetch('https://api.emailit.com/v2/contacts/export?format=csv&audience_id=aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2', {
  headers: { Authorization: 'Bearer your_api_key' },
});
await writeFile('contacts.csv', Buffer.from(await response.arrayBuffer()));
```

**Python**

```python
import requests

response = requests.get(
  "https://api.emailit.com/v2/contacts/export?format=csv&audience_id=aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2",
  headers={"Authorization": "Bearer your_api_key"}
)
with open("contacts.csv", "wb") as f:
    f.write(response.content)
```

**PHP**

```php
$ch = curl_init('https://api.emailit.com/v2/contacts/export?format=csv&audience_id=aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2');
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    'Authorization: Bearer your_api_key',
  ],
]);
file_put_contents('contacts.csv', curl_exec($ch));
curl_close($ch);
```

**Ruby**

```ruby
require "net/http"

uri = URI("https://api.emailit.com/v2/contacts/export?format=csv&audience_id=aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2")
req = Net::HTTP::Get.new(uri)
req["Authorization"] = "Bearer your_api_key"
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
File.binwrite("contacts.csv", http.request(req).body)
```

**Go**

```go
req, _ := http.NewRequest("GET", "https://api.emailit.com/v2/contacts/export?format=csv&audience_id=aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2", nil)
req.Header.Set("Authorization", "Bearer your_api_key")

resp, err := http.DefaultClient.Do(req)
if err != nil {
  return err
}
defer resp.Body.Close()

out, _ := os.Create("contacts.csv")
defer out.Close()
io.Copy(out, resp.Body)
```

**Rust**

```rust
let bytes = reqwest::Client::new()
    .get("https://api.emailit.com/v2/contacts/export?format=csv&audience_id=aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2")
    .bearer_auth("your_api_key")
    .send()
    .await?
    .bytes()
    .await?;
std::fs::write("contacts.csv", &bytes)?;
```

**Java**

```java
import java.net.http.*;
import java.net.URI;
import java.nio.file.Path;

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
  .uri(URI.create("https://api.emailit.com/v2/contacts/export?format=csv&audience_id=aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2"))
  .header("Authorization", "Bearer your_api_key")
  .GET()
  .build();
client.send(request, HttpResponse.BodyHandlers.ofFile(Path.of("contacts.csv")));
```

**.NET**

```csharp
using System.Net.Http.Headers;

var http = new HttpClient();
http.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", "your_api_key");

var bytes = await http.GetByteArrayAsync("https://api.emailit.com/v2/contacts/export?format=csv&audience_id=aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2");
await File.WriteAllBytesAsync("contacts.csv", bytes);
```

**Laravel**

```php
use Illuminate\Support\Facades\Http;
use Illuminate\Support\Facades\Storage;

$csv = Http::withToken('your_api_key')
  ->get('https://api.emailit.com/v2/contacts/export?format=csv&audience_id=aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2')
  ->body();
Storage::put('contacts.csv', $csv);
```

**cURL**

```bash
curl "https://api.emailit.com/v2/contacts/export?format=csv&audience_id=aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2" \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -o contacts.csv
```

**200**

```text
email,first_name,last_name,unsubscribed,audiences,company,plan,created_at,updated_at
ada@example.com,Ada,Lovelace,false,Newsletter,Analytical Engines,pro,2026-10-01T10:20:31.000000Z,2026-10-01T10:20:31.000000Z
```

**400**

```json
{
  "error": "format must be csv or xlsx"
}
```

**422**

```json
{
  "error": "Export is limited to 10000 contacts. Narrow your filters and try again."
}
```

---
Fonte: https://emailit.com/pt/docs/api-reference/contacts/export/

## Excluir um contato — DELETE /contacts/{id}

> Exclua um contato permanentemente e remova-o de todas as listas de contatos. Os e-mails já enviados a ele continuam nos seus logs.

# Excluir um contato

Exclui permanentemente um contato e toda a participação dele em listas de contatos.

`DELETE /contacts/{id}`

Requer uma chave de API com escopo `full`. A exclusão não pode ser desfeita. Para parar de enviar e-mails a alguém, mas manter o registro da pessoa, [atualize o contato](/pt/docs/api-reference/contacts/update/) com `unsubscribed: true` ou adicione o endereço às suas [supressões](/pt/docs/api-reference/suppressions/create/). Dispara `subscriber.deleted` para cada participação em lista e depois `contact.deleted`.

## Parâmetros de caminho

- `id` (string, obrigatório): O ID do contato (`con_…`) ou o endereço de e-mail do contato, codificado para URL.

## Retorno

- `object` (string): Sempre `contact`.

- `id` (string): O ID do contato excluído.

- `email` (string): O endereço de e-mail do contato.

- `deleted` (boolean): Sempre `true`.

**Requisição** `DELETE /contacts/{id}`

**Node.js**

```javascript
import { Emailit } from '@emailit/node';
const emailit = new Emailit('your_api_key');

await emailit.contacts.delete('con_4Kt4ZXloQR8WGcMsYx8PFCUjokM');
```

**Python**

```python
from emailit import EmailitClient
client = EmailitClient("your_api_key")

client.contacts.delete("con_4Kt4ZXloQR8WGcMsYx8PFCUjokM")
```

**PHP**

```php
$emailit = Emailit::client('your_api_key');

$emailit->contacts()->delete('con_4Kt4ZXloQR8WGcMsYx8PFCUjokM');
```

**Ruby**

```ruby
require "emailit"
client = Emailit::EmailitClient.new("your_api_key")

client.contacts.delete("con_4Kt4ZXloQR8WGcMsYx8PFCUjokM")
```

**Go**

```go
import "github.com/emailit/emailit-go/v2"
client := emailit.NewClient("your_api_key")

err := client.Contacts.Delete("con_4Kt4ZXloQR8WGcMsYx8PFCUjokM")
```

**Rust**

```rust
use emailit::Emailit;

let emailit = Emailit::new("your_api_key");

emailit.contacts.delete("con_4Kt4ZXloQR8WGcMsYx8PFCUjokM").await?;
```

**Java**

```java
import com.emailit.*;

EmailitClient emailit = new EmailitClient("your_api_key");

emailit.contacts().delete("con_4Kt4ZXloQR8WGcMsYx8PFCUjokM");
```

**.NET**

```csharp
using Emailit;

var emailit = new EmailitClient("your_api_key");

emailit.Contacts.Delete("con_4Kt4ZXloQR8WGcMsYx8PFCUjokM");
```

**Laravel**

```php
use Emailit\Laravel\Facades\Emailit;

Emailit::contacts()->delete('con_4Kt4ZXloQR8WGcMsYx8PFCUjokM');
```

**cURL**

```bash
curl -X DELETE https://api.emailit.com/v2/contacts/con_4Kt4ZXloQR8WGcMsYx8PFCUjokM \
  -H "Authorization: Bearer $EMAILIT_API_KEY"
```

**200**

```json
{
  "object": "contact",
  "id": "con_4Kt4ZXloQR8WGcMsYx8PFCUjokM",
  "email": "alan@example.com",
  "deleted": true
}
```

**404**

```json
{
  "error": "Contact not found"
}
```

---
Fonte: https://emailit.com/pt/docs/api-reference/contacts/delete/