# Kontakty API

> Spravujte profily kontaktů a vlastní pole, hromadně, nebo jednotlivě.

Základní URL: `https://api.emailit.com/v2`. Autentizujte se hlavičkou `Authorization: Bearer <API key>`.

## Vytvoření kontaktu — POST /contacts

> Vytvořte kontakt s e-mailovou adresou, jménem a vlastními poli a volitelně ho rovnou přidejte jako odběratele do jednoho nebo více seznamů kontaktů.

# Vytvoření kontaktu

Vytvoří kontakt a volitelně ho přidá jako odběratele do seznamů kontaktů.

`POST /contacts`

Vyžaduje API klíč s oprávněním `full`. E-mailové adresy jsou ve workspace jedinečné a ukládají se malými písmeny; vytvoření kontaktu, který už existuje, vrací `409` s existujícím kontaktem v poli `existing`. Vyvolá `contact.created` a pro každý seznam kontaktů `subscriber.created`. Viz [Kontakty](/cs/docs/contacts/).

## Parametry v těle požadavku

- `email` (string, povinné): E-mailová adresa kontaktu.

- `first_name` (string): Křestní jméno.

- `last_name` (string): Příjmení.

- `custom_fields` (object): Hodnoty podle klíče [vlastního pole](/cs/docs/contacts/custom-fields/), například `{"company": "Analytical Engines"}`. Hodnoty datových polí musí být ve tvaru `YYYY-MM-DD`. Klíče, které neodpovídají žádnému vlastnímu poli, se uloží tak, jak jsou.

- `audiences` (string[]): ID seznamů kontaktů (`aud_…`), do kterých se má kontakt přidat jako odběratel. ID, která ve workspace neexistují, se přeskočí.

- `unsubscribed` (boolean): `true`, pokud má kontakt vzniknout jako odhlášený. Kampaně odhlášené kontakty přeskakují a jejich členství v seznamech kontaktů začínají jako odhlášená.

## Odpověď

Vrací `201` s objektem kontaktu. Pole `audiences` tu uvádí každý seznam kontaktů s jeho `id`, `name` a stavem přihlášení `subscribed`. Všechna pole najdete na stránce [Načtení kontaktu](/cs/docs/api-reference/contacts/get/).

Pokud je některý seznam kontaktů na limitu odběratelů vašeho tarifu, vrací `422` s `usage`. V tom případě se žádný kontakt nevytvoří.

**Požadavek** `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"
  }
}
```

---
Zdroj: https://emailit.com/cs/docs/api-reference/contacts/create/

## Načtení kontaktu — GET /contacts/{id}

> Načtěte kontakt podle ID nebo e-mailové adresy s jeho vlastními poli a všemi členstvími v seznamech kontaktů, včetně dat přihlášení.

# Načtení kontaktu

Načte kontakt s jeho vlastními poli a členstvími v seznamech kontaktů.

`GET /contacts/{id}`

Vyžaduje API klíč s oprávněním `full`.

## Parametry v cestě

- `id` (string, povinné): ID kontaktu (`con_…`), nebo e-mailová adresa kontaktu zakódovaná pro URL.

## Odpověď

Vrací objekt kontaktu.

- `object` (string): Vždy `contact`.

- `id` (string): ID kontaktu.

- `email` (string): E-mailová adresa, malými písmeny.

- `first_name` (string | null): Křestní jméno.

- `last_name` (string | null): Příjmení.

- `custom_fields` (object): Hodnoty vlastních polí podle klíče. `{}`, pokud žádné nejsou.

- `unsubscribed` (boolean): `true`, pokud se kontakt odhlásil ze všech kampaní.

- `audiences` (object[]): Seznamy kontaktů, do kterých kontakt patří, každý s `id`, `name` a objektem `subscriber`: `id` (`sub_…`), `subscribed`, `subscribed_at`, `unsubscribed_at`, `created_at` a `updated_at`.

- `created_at` (string): Kdy byl kontakt vytvořen.

- `updated_at` (string): Kdy byl kontakt naposledy změněn.

**Požadavek** `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"
}
```

---
Zdroj: https://emailit.com/cs/docs/api-reference/contacts/get/

## Úprava kontaktu — POST /contacts/{id}

> Změňte e-mailovou adresu, jméno, vlastní pole nebo stav odhlášení kontaktu, nebo nahraďte seznamy kontaktů, do kterých patří.

# Úprava kontaktu

Upraví kontakt. Změní se jen pole, která pošlete.

`POST /contacts/{id}`

Vyžaduje API klíč s oprávněním `full`. Vyvolá `contact.updated` s předchozími hodnotami změněných polí v `previous`. Změna `audiences` navíc vyvolá `subscriber.created` a `subscriber.deleted` pro členství, která přidá a odebere.

## Parametry v cestě

- `id` (string, povinné): ID kontaktu (`con_…`), nebo e-mailová adresa kontaktu zakódovaná pro URL.

## Parametry v těle požadavku

- `email` (string): Nová e-mailová adresa. Nesmí patřit jinému kontaktu.

- `first_name` (string): Křestní jméno.

- `last_name` (string): Příjmení.

- `custom_fields` (object): Hodnoty vlastních polí podle klíče. Nahradí všechna vlastní pole kontaktu, takže uveďte i ta, která chcete zachovat.

- `unsubscribed` (boolean): `true` kontakt odhlásí ze všech kampaní, `false` ho znovu přihlásí. Stávající členství v seznamech kontaktů si zachovají svůj vlastní stav.

- `audiences` (string[]): Úplný výčet ID seznamů kontaktů, do kterých má kontakt patřit. Kontakt se přidá do seznamů z vašeho výčtu, ve kterých ještě není, a odebere se ze seznamů, které ve vašem výčtu nejsou. Pokud ho chcete odebrat ze všech seznamů, pošlete `[]`. Pokud chcete přidat nebo odebrat jeden seznam bez vypisování všech ostatních, použijte endpoint [Přidání odběratele](/cs/docs/api-reference/audiences/subscribers/add/), nebo [Smazání odběratele](/cs/docs/api-reference/audiences/subscribers/delete/).

## Odpověď

Vrací upravený kontakt ve stejném formátu jako endpoint [Načtení kontaktu](/cs/docs/api-reference/contacts/get/). Požadavek, který neobsahuje žádné z těchto polí, vrací `400`.

**Požadavek** `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"
}
```

---
Zdroj: https://emailit.com/cs/docs/api-reference/contacts/update/

## Výpis kontaktů — GET /contacts

> Vypište kontakty workspace od nejnovějších a filtrujte je podle seznamu kontaktů, stavu přihlášení, vlastních polí nebo libovolného pole kontaktu.

# Výpis kontaktů

Vrací stránku kontaktů od nejnovějších.

`GET /contacts`

Vyžaduje API klíč s oprávněním `full`. Se stejnými parametry můžete přes endpoint [Export kontaktů](/cs/docs/api-reference/contacts/export/) stáhnout všechny odpovídající kontakty jako soubor.

## Parametry dotazu

- `page` (integer): Stránka, kterou chcete načíst.

- `limit` (integer): Počet kontaktů na stránce, od 1 do 100.

- `search` (string): Hledá v e-mailové adrese, křestním jménu nebo příjmení bez ohledu na velikost písmen. Funguje i `q`.

- `audience_id` (string): Jen kontakty v tomto seznamu kontaktů (`aud_…`).

- `unsubscribed` (boolean): `true`, nebo `false`. Jen kontakty s tímto stavem odhlášení.

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

- `order` (string): `asc`, nebo `desc`. U tohoto endpointu je `order` směr řazení, ne klíč řazení.

- `match` (string): `all`, nebo `or`. Určuje, jak se kombinují filtry níže.

## Filtry

Filtry přidejte ve tvaru `key.condition=value`, například `email.ends_with=@acme.com` nebo `custom_fields.plan.exact=pro`. Viz [Filtrování a řazení](/cs/docs/api-reference/filtering/).

| Klíč | Typ | Poznámky |
| --- | --- | --- |
| `email` | string | |
| `first_name` | string | |
| `last_name` | string | |
| `name` | string | Křestní jméno a příjmení spojené mezerou. |
| `audiences` | string | Abecedně první název seznamu kontaktů, do kterého kontakt patří. |
| `unsubscribed` | boolean | |
| `created_at` | date | |
| `updated_at` | date | |
| `audience_id` | string | Jen `exact` a `not_exact`. Hodnota je ID seznamu kontaktů. |
| `custom_fields.<key>` | string | Místo `<key>` dosaďte klíč vlastního pole. Hodnoty se porovnávají jako text. |

Starší parametry `filter[audience_id]`, `filter[unsubscribed]` a `filter[custom_fields][<key>]` stále fungují.

## Odpověď

- `data` (object[]): Kontakty na této stránce, každý s `audiences` ve tvaru `id`, `name` a `subscribed`. Viz [Načtení kontaktu](/cs/docs/api-reference/contacts/get/).

- `total_records` (integer): Počet odpovídajících kontaktů napříč všemi stránkami.

- `next_page_url` (string | null): Cesta k další stránce s vašimi filtry, nebo `null`. Viz [Stránkování](/cs/docs/api-reference/pagination/).

- `previous_page_url` (string | null): Cesta k předchozí stránce, nebo `null`.

**Požadavek** `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
}
```

---
Zdroj: https://emailit.com/cs/docs/api-reference/contacts/list/

## Hromadná úprava kontaktů — POST /contacts/bulk

> Proveďte jednu akci až se 100 kontakty najednou: smažte je, přidejte je do seznamu kontaktů nebo je z něj odeberte, odhlaste je nebo je znovu přihlaste.

# Hromadná úprava kontaktů

Provede jednu akci až se 100 kontakty v jediném požadavku.

`POST /contacts/bulk`

Vyžaduje API klíč s oprávněním `full`. Každé ID musí patřit kontaktu ve workspace, jinak se nic nezmění a odpověď vypíše chybějící ID v poli `missing`. Každý kontakt vyvolá stejné události jako endpointy pro jednotlivé kontakty. Pokud seznam kontaktů během `add_to_audience` dosáhne limitu odběratelů vašeho tarifu, požadavek skončí s `422` a kontakty zpracované do té doby zůstanou přidané.

| Akce | Co dělá |
| --- | --- |
| `delete` | Smaže kontakty a jejich členství v seznamech kontaktů, stejně jako [Smazání kontaktu](/cs/docs/api-reference/contacts/delete/). |
| `add_to_audience` | Přidá kontakty do seznamu `audience_id`. Kontakty, které v něm už jsou, zůstanou beze změny. |
| `remove_from_audience` | Odebere kontakty ze seznamu `audience_id`. |
| `unsubscribe` | Nastaví `unsubscribed` na `true`, takže kampaně kontakty přeskočí. |
| `resubscribe` | Nastaví `unsubscribed` na `false`. |

## Parametry v těle požadavku

- `action` (string, povinné): `delete`, `add_to_audience`, `remove_from_audience`, `unsubscribe` nebo `resubscribe`.

- `ids` (string[], povinné): ID kontaktů (`con_…`), od 1 do 100. E-mailové adresy se tu nepřijímají. Duplicity se ignorují.

- `audience_id` (string): ID seznamu kontaktů. Povinné pro `add_to_audience` a `remove_from_audience`.

## Odpověď

- `object` (string): Vždy `contact_bulk`.

- `action` (string): Akce, která proběhla.

- `processed` (integer): Kolik kontaktů se zpracovalo.

- `ids` (string[]): ID zpracovaných kontaktů.

**Požadavek** `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"
  }
}
```

---
Zdroj: https://emailit.com/cs/docs/api-reference/contacts/bulk/

## Export kontaktů — GET /contacts/export

> Stáhněte kontakty odpovídající vašim filtrům jako soubor CSV nebo Excel, včetně jejich seznamů kontaktů a vlastních polí. Nejvýše 10 000 kontaktů.

# Export kontaktů

Stáhne odpovídající kontakty jako soubor CSV nebo XLSX.

`GET /contacts/export`

Vyžaduje API klíč s oprávněním `full`. Přijímá stejné parametry vyhledávání, filtrování a řazení jako [Výpis kontaktů](/cs/docs/api-reference/contacts/list/), předané v řetězci dotazu, ale bez stránkování. `POST /contacts/export` funguje stejně. Export může obsahovat nejvýše 10 000 kontaktů; pokud jich odpovídá víc, požadavek vrátí `422`, takže filtry zužte.

## Parametry dotazu

- `format` (string): `csv`, nebo `xlsx`.

- `search, audience_id, unsubscribed, sort, order, match, key.condition` (string): Stejné parametry jako u endpointu [Výpis kontaktů](/cs/docs/api-reference/contacts/list/).

## Odpověď

Vrací soubor jako přílohu: `contacts.csv` (`text/csv; charset=utf-8`), nebo `contacts.xlsx`. Každý řádek je jeden kontakt s těmito sloupci:

| Sloupec | Obsah |
| --- | --- |
| `email` | E-mailová adresa. |
| `first_name`, `last_name` | Křestní jméno a příjmení. |
| `unsubscribed` | `true`, nebo `false`. |
| `audiences` | Názvy seznamů kontaktů, do kterých kontakt patří, oddělené `; `. |
| Jeden sloupec pro každé vlastní pole | Hodnota každého vlastního pole definovaného ve workspace; sloupec se jmenuje podle klíče pole. Více hodnot se spojuje znakem `;`. |
| `created_at`, `updated_at` | Časová razítka ISO 8601. |

**Požadavek** `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."
}
```

---
Zdroj: https://emailit.com/cs/docs/api-reference/contacts/export/

## Smazání kontaktu — DELETE /contacts/{id}

> Trvale smažte kontakt a odeberte ho ze všech seznamů kontaktů. E-maily, které mu už byly odeslány, zůstanou ve vašich logech.

# Smazání kontaktu

Trvale smaže kontakt a všechna jeho členství v seznamech kontaktů.

`DELETE /contacts/{id}`

Vyžaduje API klíč s oprávněním `full`. Smazání nelze vrátit zpět. Pokud chcete někomu přestat posílat e-maily, ale jeho záznam si ponechat, [upravte kontakt](/cs/docs/api-reference/contacts/update/) a nastavte `unsubscribed: true`, nebo adresu přidejte na [seznam blokovaných adres](/cs/docs/api-reference/suppressions/create/). Vyvolá `subscriber.deleted` pro každé členství a potom `contact.deleted`.

## Parametry v cestě

- `id` (string, povinné): ID kontaktu (`con_…`), nebo e-mailová adresa kontaktu zakódovaná pro URL.

## Odpověď

- `object` (string): Vždy `contact`.

- `id` (string): ID smazaného kontaktu.

- `email` (string): E-mailová adresa kontaktu.

- `deleted` (boolean): Vždy `true`.

**Požadavek** `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"
}
```

---
Zdroj: https://emailit.com/cs/docs/api-reference/contacts/delete/