# Contactos API

> Gestiona los perfiles de contacto y los campos personalizados, de forma masiva o de uno en uno.

URL base: `https://api.emailit.com/v2`. Autentícate con `Authorization: Bearer <API key>`.

## Crear un contacto — POST /contacts

> Crea un contacto con una dirección de email, un nombre, unos apellidos y campos personalizados y, si quieres, suscríbelo a la vez a una o varias listas de contactos.

# Crear un contacto

Crea un contacto y, opcionalmente, lo suscribe a listas de contactos.

`POST /contacts`

Requiere una clave de API `full`. Las direcciones de email son únicas en cada espacio de trabajo y se guardan en minúsculas; si creas un contacto que ya existe, la petición devuelve `409` con el contacto en `existing`. Dispara `contact.created` y, por cada lista, `subscriber.created`. Consulta [Contactos](/es/docs/contacts/).

## Parámetros del cuerpo

- `email` (string, obligatorio): La dirección de email del contacto.

- `first_name` (string): El nombre.

- `last_name` (string): Los apellidos.

- `custom_fields` (object): Los valores por clave de [campo personalizado](/es/docs/contacts/custom-fields/), como `{"company": "Analytical Engines"}`. Los valores de los campos de fecha deben tener el formato `YYYY-MM-DD`. Las claves que no coinciden con ningún campo personalizado se guardan tal cual.

- `audiences` (string[]): Los ID de las listas (`aud_…`) a las que se suscribe el contacto. Los ID que no existen en el espacio de trabajo se omiten.

- `unsubscribed` (boolean): `true` para crear el contacto como dado de baja. Las campañas omiten a los contactos dados de baja, y sus pertenencias a listas empiezan como dadas de baja.

## Devuelve

Devuelve `201` con el objeto de contacto. Aquí, `audiences` enumera cada lista con su `id`, su `name` y su estado `subscribed`. Para ver todos los campos, consulta [Obtener un contacto](/es/docs/api-reference/contacts/get/).

Devuelve `422` con `usage` si una lista ha alcanzado el límite de suscriptores de tu plan. En ese caso, no se crea ningún contacto.

**Petición** `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"
  }
}
```

---
Fuente: https://emailit.com/es/docs/api-reference/contacts/create/

## Obtener un contacto — GET /contacts/{id}

> Obtén un contacto por su ID o su dirección de email, con sus campos personalizados y todas sus pertenencias a listas de contactos, incluidas las fechas de suscripción.

# Obtener un contacto

Obtiene un contacto con sus campos personalizados y sus pertenencias a listas.

`GET /contacts/{id}`

Requiere una clave de API `full`.

## Parámetros de ruta

- `id` (string, obligatorio): El ID del contacto (`con_…`) o su dirección de email, codificada para URL.

## Devuelve

Devuelve el objeto de contacto.

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

- `id` (string): El ID del contacto.

- `email` (string): La dirección de email, en minúsculas.

- `first_name` (string | null): El nombre.

- `last_name` (string | null): Los apellidos.

- `custom_fields` (object): Los valores de los campos personalizados por clave. `{}` si no hay ninguno.

- `unsubscribed` (boolean): `true` si el contacto se ha dado de baja de todas las campañas.

- `audiences` (object[]): Las listas a las que pertenece el contacto, cada una con `id`, `name` y un objeto `subscriber`: `id` (`sub_…`), `subscribed`, `subscribed_at`, `unsubscribed_at`, `created_at` y `updated_at`.

- `created_at` (string): Cuándo se creó el contacto.

- `updated_at` (string): Cuándo se modificó el contacto por última vez.

**Petición** `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"
}
```

---
Fuente: https://emailit.com/es/docs/api-reference/contacts/get/

## Actualizar un contacto — POST /contacts/{id}

> Cambia la dirección de email, el nombre, los apellidos, los campos personalizados o el estado de baja de un contacto, o sustituye las listas de contactos a las que pertenece.

# Actualizar un contacto

Actualiza un contacto. Solo cambian los campos que envíes.

`POST /contacts/{id}`

Requiere una clave de API `full`. Dispara `contact.updated`, con los valores anteriores de los campos modificados en `previous`. Cambiar `audiences` también dispara `subscriber.created` y `subscriber.deleted` por las pertenencias que añade y elimina.

## Parámetros de ruta

- `id` (string, obligatorio): El ID del contacto (`con_…`) o su dirección de email, codificada para URL.

## Parámetros del cuerpo

- `email` (string): Una nueva dirección de email. No puede pertenecer a otro contacto.

- `first_name` (string): El nombre.

- `last_name` (string): Los apellidos.

- `custom_fields` (object): Los valores de los campos personalizados por clave. Sustituye todos los campos personalizados del contacto, así que incluye los que quieras conservar.

- `unsubscribed` (boolean): `true` para dar de baja al contacto de todas las campañas, `false` para volver a suscribirlo. Las pertenencias a listas existentes conservan su propio estado.

- `audiences` (string[]): La lista completa de ID de las listas de contactos a las que debe pertenecer el contacto. El contacto se añade a las listas en las que aún no está y se quita de las que no están en tu lista. Envía `[]` para quitarlo de todas las listas. Para añadirlo a una lista o quitarlo de ella sin enumerar todas, usa [Añadir un suscriptor](/es/docs/api-reference/audiences/subscribers/add/) o [Eliminar un suscriptor](/es/docs/api-reference/audiences/subscribers/delete/).

## Devuelve

Devuelve el contacto actualizado en el mismo formato que [Obtener un contacto](/es/docs/api-reference/contacts/get/). Una petición sin ninguno de estos campos devuelve `400`.

**Petición** `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"
}
```

---
Fuente: https://emailit.com/es/docs/api-reference/contacts/update/

## Listar contactos — GET /contacts

> Obtén los contactos de un espacio de trabajo, del más reciente al más antiguo, filtrados por lista de contactos, estado de suscripción, campos personalizados o cualquier campo del contacto.

# Listar contactos

Devuelve una página de contactos, del más reciente al más antiguo.

`GET /contacts`

Requiere una clave de API `full`. Usa los mismos parámetros con [Exportar contactos](/es/docs/api-reference/contacts/export/) para descargar en un archivo todos los contactos que coincidan.

## Parámetros de consulta

- `page` (integer): La página que se devuelve.

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

- `search` (string): Búsqueda en la dirección de email, el nombre o los apellidos, sin distinguir mayúsculas y minúsculas. También funciona `q`.

- `audience_id` (string): Solo los contactos de esta lista (`aud_…`).

- `unsubscribed` (boolean): `true` o `false`. Solo los contactos con este estado de baja.

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

- `order` (string): `asc` o `desc`. En este endpoint, `order` es la dirección de la ordenación, no la clave por la que se ordena.

- `match` (string): `all` u `or`. Cómo se combinan los filtros de abajo.

## Filtros

Añade filtros con el formato `key.condition=value`, por ejemplo `email.ends_with=@acme.com` o `custom_fields.plan.exact=pro`. Consulta [Filtrado](/es/docs/api-reference/filtering/).

| Clave | Tipo | Notas |
| --- | --- | --- |
| `email` | cadena | |
| `first_name` | cadena | |
| `last_name` | cadena | |
| `name` | cadena | El nombre y los apellidos unidos con un espacio. |
| `audiences` | cadena | El primer nombre de lista del contacto por orden alfabético. |
| `unsubscribed` | booleano | |
| `created_at` | fecha | |
| `updated_at` | fecha | |
| `audience_id` | cadena | Solo `exact` y `not_exact`. El valor es un ID de lista. |
| `custom_fields.<key>` | cadena | Sustituye `<key>` por la clave de un campo personalizado. Los valores se comparan como texto. |

Los parámetros antiguos `filter[audience_id]`, `filter[unsubscribed]` y `filter[custom_fields][<key>]` siguen funcionando.

## Devuelve

- `data` (object[]): Los contactos de esta página, cada uno con `audiences` en forma de `id`, `name` y `subscribed`. Consulta [Obtener un contacto](/es/docs/api-reference/contacts/get/).

- `total_records` (integer): El número de contactos que coinciden, en todas las páginas.

- `next_page_url` (string | null): La ruta de la página siguiente con tus filtros, o `null`. Consulta [Paginación](/es/docs/api-reference/pagination/).

- `previous_page_url` (string | null): La ruta de la página anterior, o `null`.

**Petición** `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
}
```

---
Fuente: https://emailit.com/es/docs/api-reference/contacts/list/

## Actualizar contactos de forma masiva — POST /contacts/bulk

> Aplica una acción a hasta 100 contactos a la vez: eliminarlos, añadirlos a una lista de contactos o quitarlos de ella, darlos de baja o volver a suscribirlos.

# Actualizar contactos de forma masiva

Ejecuta una acción sobre hasta 100 contactos en una sola petición.

`POST /contacts/bulk`

Requiere una clave de API `full`. Todos los ID deben pertenecer a contactos del espacio de trabajo; si no, no se cambia nada y la respuesta enumera en `missing` los ID que no existen. Cada contacto dispara los mismos eventos que los endpoints de un solo contacto. Si la lista alcanza el límite de suscriptores de tu plan durante `add_to_audience`, la petición se detiene con `422`, y los contactos procesados hasta ese momento siguen añadidos.

| Acción | Qué hace |
| --- | --- |
| `delete` | Elimina los contactos y sus pertenencias a listas, como [Eliminar un contacto](/es/docs/api-reference/contacts/delete/). |
| `add_to_audience` | Añade los contactos a `audience_id`. Los contactos que ya están en ella no se modifican. |
| `remove_from_audience` | Quita los contactos de `audience_id`. |
| `unsubscribe` | Establece `unsubscribed` en `true`, de modo que las campañas omiten a esos contactos. |
| `resubscribe` | Establece `unsubscribed` en `false`. |

## Parámetros del cuerpo

- `action` (string, obligatorio): `delete`, `add_to_audience`, `remove_from_audience`, `unsubscribe` o `resubscribe`.

- `ids` (string[], obligatorio): Los ID de los contactos (`con_…`), de 1 a 100. Aquí no se aceptan direcciones de email. Los duplicados se ignoran.

- `audience_id` (string): El ID de la lista. Obligatorio para `add_to_audience` y `remove_from_audience`.

## Devuelve

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

- `action` (string): La acción que se ejecutó.

- `processed` (integer): Cuántos contactos se procesaron.

- `ids` (string[]): Los ID de los contactos procesados.

**Petición** `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"
  }
}
```

---
Fuente: https://emailit.com/es/docs/api-reference/contacts/bulk/

## Exportar contactos — GET /contacts/export

> Descarga en un archivo CSV o Excel los contactos que coinciden con tus filtros, con sus listas de contactos y sus campos personalizados. Hasta 10.000 contactos.

# Exportar contactos

Descarga los contactos que coinciden en un archivo CSV o XLSX.

`GET /contacts/export`

Requiere una clave de API `full`. Acepta los mismos parámetros de búsqueda, filtrado y ordenación que [Listar contactos](/es/docs/api-reference/contacts/list/), en la cadena de consulta y sin paginación. `POST /contacts/export` funciona igual. Una exportación puede incluir hasta 10.000 contactos; si coinciden más, la petición devuelve `422`, así que acota los filtros.

## Parámetros de consulta

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

- `search, audience_id, unsubscribed, sort, order, match, key.condition` (string): Los mismos parámetros que [Listar contactos](/es/docs/api-reference/contacts/list/).

## Devuelve

Devuelve el archivo como adjunto: `contacts.csv` (`text/csv; charset=utf-8`) o `contacts.xlsx`. Cada fila es un contacto con estas columnas:

| Columna | Contenido |
| --- | --- |
| `email` | La dirección de email. |
| `first_name`, `last_name` | El nombre y los apellidos. |
| `unsubscribed` | `true` o `false`. |
| `audiences` | Los nombres de las listas del contacto, separados por `; `. |
| Una columna por campo personalizado | El valor de cada campo personalizado definido en el espacio de trabajo, con su clave como nombre de columna. Los valores múltiples se unen con `;`. |
| `created_at`, `updated_at` | Marcas de tiempo en formato ISO 8601. |

**Petición** `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."
}
```

---
Fuente: https://emailit.com/es/docs/api-reference/contacts/export/

## Eliminar un contacto — DELETE /contacts/{id}

> Elimina de forma permanente un contacto y quítalo de todas las listas de contactos. Los emails que ya se le enviaron siguen en tus registros de emails.

# Eliminar un contacto

Elimina de forma permanente un contacto y todas sus pertenencias a listas.

`DELETE /contacts/{id}`

Requiere una clave de API `full`. La eliminación no se puede deshacer. Para dejar de enviar emails a alguien sin perder sus datos, [actualiza el contacto](/es/docs/api-reference/contacts/update/) con `unsubscribed: true` o añade la dirección a tus [direcciones bloqueadas](/es/docs/api-reference/suppressions/create/). Dispara `subscriber.deleted` por cada pertenencia y, después, `contact.deleted`.

## Parámetros de ruta

- `id` (string, obligatorio): El ID del contacto (`con_…`) o su dirección de email, codificada para URL.

## Devuelve

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

- `id` (string): El ID del contacto eliminado.

- `email` (string): La dirección de email del contacto.

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

**Petición** `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"
}
```

---
Fuente: https://emailit.com/es/docs/api-reference/contacts/delete/