# Import a export kontaktů

> Naimportujte kontakty ze souboru CSV nebo Excel v průvodci importem, vyexportujte vyfiltrované kontakty do CSV nebo XLSX a spouštějte hromadné akce a exporty přes API.

V průvodci importem přenesete kontakty z tabulky a exportem stáhnete kontakty, které odpovídají aktuálním filtrům. Tato stránka popisuje také hromadné akce a endpoint pro export v API, se kterými totéž uděláte z kódu.

## Než začnete

- Vytvořte všechna [vlastní pole](/cs/docs/contacts/custom-fields/), která chcete ze souboru vyplnit. Průvodce umí namapovat sloupce jen na pole, která už existují.
- Vytvořte [seznamy kontaktů](/cs/docs/audiences/), do kterých se mají kontakty přidat. Importy se počítají do limitu odběratelů každého seznamu.
- Importujte jen lidi, kteří s odběrem souhlasili. Při kontrole žádosti o produkční přístup se ptáme, jak odběratele získáváte. Viz [Produkční přístup (ověření workspace)](/cs/docs/workspaces/production-access/).

## Připravte soubor

Průvodce čte soubory `.csv`, `.xlsx` a `.xls` s nejvýše **2 500 kontakty na soubor**. Větší seznamy rozdělte do více souborů.

```csv title="contacts.csv"
email,first_name,last_name,company,birthday
ada@example.com,Ada,Lovelace,Acme,1990-04-12
grace@example.com,Grace,Hopper,Acme,1906-12-09
alan@example.com,Alan,Turing,,
```

Tipy pro čistý import:

- **Na každý řádek dejte jeden kontakt** a do prvního řádku názvy sloupců. Ze souborů Excel se čte jen první list.
- **Pojmenujte sloupce podle svých polí** a průvodce je namapuje za vás. Záhlaví sloupce se namapuje automaticky, když odpovídá názvu nebo klíči pole bez ohledu na velikost písmen, například `email`, `First name`, `first_name` nebo klíč vlastního pole jako `company`.
- **Soubory CSV ukládejte v UTF-8**, aby se jména s diakritikou načetla správně.
- **Data zapisujte ve tvaru `YYYY-MM-DD`.** Fungují i datumové buňky v souborech Excel. Jiné formáty data se odmítnou.
- **Zkontrolujte adresy.** Jediná neplatná e-mailová adresa zastaví celý import s chybou, která uvádí číslo řádku, například „Contact #12 has an invalid email address.“ Řádky s prázdnou buňkou e-mailu se přeskočí.
- **Hodnoty vícevýběrových polí** se naimportují jako jedna textová hodnota. Pokud chcete uložit více možností jako seznam, nastavte je přes API.

## Naimportujte kontakty

1. **Otevřete průvodce.** Přejděte do **Email Marketing → Contacts** a vyberte **Import**.

2. **Vyberte soubor.** V poli **CSV File** vyberte svůj soubor. Pokud první řádek obsahuje názvy sloupců, nechte zaškrtnuté **File has header**. Průvodce ukáže první řádky a celkový počet řádků, a pokud má soubor víc než 2 500 řádků, zobrazí varování. Vyberte **Continue**.

3. **Namapujte sloupce.** U každého sloupce vyberte pole kontaktu, které vyplňuje: **Email**, **First name**, **Last name**, některé z vašich vlastních polí, nebo **Exclude**, pokud ho chcete přeskočit. Jeden sloupec musíte namapovat na **Email**. Každý řádek ukazuje ukázkové hodnoty, abyste mapování mohli zkontrolovat.

4. **Vyberte seznamy kontaktů.** V poli **Audiences** zvolte seznamy, do kterých se mají kontakty přidat, nebo ho nechte prázdné a kontakty naimportujte bez přidání do seznamu. Vyberte **Continue**.

5. **Zkontrolujte a naimportujte.** Náhled ukazuje soubor, počet kontaktů, seznamy, mapování sloupců a prvních 10 kontaktů tak, jak se uloží. Vyberte **Import**.

Emailit nejdřív zkontroluje celý soubor. Pokud je něco špatně, například neplatná adresa, neznámé vlastní pole nebo plný seznam, nenaimportuje se nic a chyby se vypíšou, abyste soubor mohli opravit. Jinak import proběhne na pozadí v dávkách po 500. Po chvíli obnovte stránku Contacts a uvidíte nové kontakty.

### Co se stane s existujícími kontakty

Kontakty se párují podle e-mailové adresy bez ohledu na velikost písmen.

| Případ | Výsledek |
| --- | --- |
| Adresa je nová | Vytvoří se kontakt. |
| Adresa už existuje | Kontakt se upraví. Jména se přepíšou, jen když má soubor hodnotu. Hodnoty vlastních polí ze souboru nahradí uložené a prázdná buňka v namapovaném sloupci vlastního pole toto pole vymaže. Ostatní vlastní pole zůstanou. |
| Adresa je v souboru dvakrát | Použijí se oba řádky v pořadí, takže platí ten pozdější. |
| Kontakt ve vybraném seznamu ještě není | Přidá se do seznamu jako přihlášený. |
| Kontakt se z vybraného seznamu odhlásil | Znovu se k seznamu přihlásí. |

> **Importy lidi znovu přihlašují:** Import kontaktu do seznamu, ze kterého se odhlásil, ho znovu přihlásí. Před importem do existujícího seznamu odstraňte ze souboru lidi, kteří se odhlásili, nebo importujte bez výběru tohoto seznamu.

Několik dalších věcí, které je dobré vědět:

- Seznam pro mapování obsahuje **Unsubscribed**, ale import ho nepoužije. Pokud chcete naimportované lidi označit jako odhlášené, vyberte je potom na stránce Contacts a použijte hromadnou akci **Unsubscribe**.
- Importy nevyvolávají události webhooků `contact.*` ani `subscriber.*` a nespouštějí automatizace, jako je **Added to audience**.
- Pokud by seznam překročil limit odběratelů, import se odmítne se zprávou, která limit uvádí, například „Pay as you go includes 10,000 subscribers per audience.“ Viz [Seznamy kontaktů](/cs/docs/audiences/#limits).

## Vyexportujte kontakty

1. **Zužte seznam.** Na stránce **Email Marketing → Contacts** zobrazte vyhledáváním a tlačítkem **Filter** kontakty, které chcete. Bez vyhledávání a filtrů export obsahuje všechny kontakty.

2. **Vyexportujte.** Vyberte **Export** a zvolte **CSV**, nebo **XLSX**. Prohlížeč stáhne `contacts.csv`, nebo `contacts.xlsx`.

Export může obsahovat nejvýše **10 000 kontaktů**. Pokud jich odpovídá víc, export selže, takže přidejte filtry, například seznam kontaktů nebo rozsah data vytvoření, a exportujte po částech.

Soubor má jeden řádek na kontakt a tyto sloupce:

| Sloupec | Hodnota |
| --- | --- |
| `email` | E-mailová adresa kontaktu. |
| `first_name`, `last_name` | Jména kontaktu. |
| `unsubscribed` | `true`, pokud je marketingový stav **Unsubscribed**, jinak `false`. |
| `audiences` | Názvy všech seznamů, ve kterých kontakt je, oddělené `; `. |
| Jeden sloupec pro každý klíč vlastního pole | Uložená hodnota. Hodnoty vícevýběrových polí se spojí znakem `;`. |
| `created_at`, `updated_at` | Časová razítka ve formátu ISO 8601. |

## Práce s API

API nemá import souborů. Pokud chcete z kódu přidat mnoho kontaktů, zavolejte pro každý endpoint [Vytvoření kontaktu](/cs/docs/api-reference/contacts/create/), nebo [Přidání odběratele](/cs/docs/api-reference/audiences/subscribers/add/), který jedním voláním vytvoří kontakt i jeho členství v seznamu.

### Hromadné akce

[`POST /v2/contacts/bulk`](/cs/docs/api-reference/contacts/bulk/) provede jednu akci až na 100 kontaktech zadaných podle ID `con_`:

| `action` | Účinek | Potřebuje `audience_id` |
| --- | --- | --- |
| `add_to_audience` | Přidá kontakty do seznamu. Kontakty s `unsubscribed: true` se přidají jako odhlášené. | Ano |
| `remove_from_audience` | Smaže jejich členství v seznamu. | Ano |
| `unsubscribe` | Nastaví `unsubscribed: true` (marketingový stav **Unsubscribed**). | Ne |
| `resubscribe` | Nastaví `unsubscribed: false`. | Ne |
| `delete` | Smaže kontakty i jejich členství. | Ne |

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

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

Požadavek selže celý, pokud má `ids` víc než 100 položek (`400`), nebo pokud některý kontakt či seznam neexistuje (`404`, s neznámými ID v poli `missing`). Pokud chcete zpracovat víc kontaktů, procházejte stránky výsledků endpointu [Výpis kontaktů](/cs/docs/api-reference/contacts/list/) a posílejte dávky po 100.

### Export

[`GET /v2/contacts/export`](/cs/docs/api-reference/contacts/export/) vrací stejný soubor jako webové rozhraní. Nastavte `format` na `csv` (výchozí), nebo `xlsx` a přidejte libovolné filtry, vyhledávání a řazení z endpointu [Výpis kontaktů](/cs/docs/api-reference/contacts/list/):

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

Pokud odpovídá víc než 10 000 kontaktů, endpoint vrací `422` se zprávou „Export is limited to 10000 contacts. Narrow your filters and try again.“

## Související

  - [Vlastní pole](/cs/docs/contacts/custom-fields/): Definujte pole, na která se mapují vaše sloupce.
  - [Odběratelé](/cs/docs/audiences/subscribers/): Spravujte, kdo je v jednotlivých seznamech.

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