Kontakty

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

Základní URLhttps://api.emailit.com/v2Autentizace Chyby Limity rychlosti

POST/contacts
GET/contacts/{id}
POST/contacts/{id}
GET/contacts
POST/contacts/bulk
POST/contacts/{id}/tags
DEL/contacts/{id}/tags
GET/contacts/tags
POST/contacts/{id}/score
GET/contacts/export
DEL/contacts/{id}

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.

Parametry v těle požadavku

emailstringpovinné

E-mailová adresa kontaktu.

first_namestring

Křestní jméno.

last_namestring

Příjmení.

custom_fieldsobject

Hodnoty podle klíče vlastního pole, 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.

audiencesstring[]

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

tagsstring[]

Nejvýše 50 štítků, které se uloží malými písmeny.

scoreintegervýchozí: 0

Počáteční skóre kontaktu.

unsubscribedbooleanvýchozí: false

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.

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ří.

POST/contacts

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

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

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

PHP

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

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

Ruby

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

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

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

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

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()
);

using Emailit;

var emailit = new EmailitClient("your_api_key");

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

PHP

use Emailit\Laravel\Facades\Emailit;

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

Terminal

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"]
  }'

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"
}

JSON

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

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"
  }
}

JSON

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

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ě

idstringpovinné

ID kontaktu (con_…), nebo e-mailová adresa kontaktu zakódovaná pro URL.

Odpověď

Vrací objekt kontaktu.

objectstring

Vždy contact.

idstring

ID kontaktu.

emailstring

E-mailová adresa, malými písmeny.

first_namestring | null

Křestní jméno.

last_namestring | null

Příjmení.

custom_fieldsobject

Hodnoty vlastních polí podle klíče. {}, pokud žádné nejsou.

unsubscribedboolean

true, pokud se kontakt odhlásil ze všech kampaní.

tagsstring[]

Štítky kontaktu, malými písmeny a seřazené.

scoreinteger

Skóre kontaktu.

audiencesobject[]

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_atstring

Kdy byl kontakt vytvořen.

updated_atstring

Kdy byl kontakt naposledy změněn.

GET/contacts/{id}

JavaScript

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

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

Python

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

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

PHP

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

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

Ruby

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

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

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

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

Rust

use emailit::Emailit;

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

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

Java

import com.emailit.*;

EmailitClient emailit = new EmailitClient("your_api_key");

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

using Emailit;

var emailit = new EmailitClient("your_api_key");

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

PHP

use Emailit\Laravel\Facades\Emailit;

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

Terminal

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

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"
}

JSON

{
  "error": "Contact not found"
}

Ú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ě

idstringpovinné

ID kontaktu (con_…), nebo e-mailová adresa kontaktu zakódovaná pro URL.

Parametry v těle požadavku

emailstring

Nová e-mailová adresa. Nesmí patřit jinému kontaktu.

first_namestring

Křestní jméno.

last_namestring

Příjmení.

custom_fieldsobject

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

unsubscribedboolean

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.

tagsstring[]

Nahradí všechny štítky kontaktu. [] odebere všechny.

add_tagsstring[]

Štítky, které se mají přidat; ostatní zůstanou.

remove_tagsstring[]

Štítky, které se mají odebrat.

scoreinteger

Nastaví skóre kontaktu. Pokud chcete body přičíst nebo odečíst, použijte Změnu skóre kontaktu.

audiencesstring[]

Ú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, nebo Smazání odběratele.

Odpověď

Vrací upravený kontakt ve stejném formátu jako endpoint Načtení kontaktu. Požadavek, který neobsahuje žádné z těchto polí, vrací 400.

POST/contacts/{id}

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

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

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

PHP

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

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

Ruby

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

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

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

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

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()
);

using Emailit;

var emailit = new EmailitClient("your_api_key");

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

PHP

use Emailit\Laravel\Facades\Emailit;

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

Terminal

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"}'

Terminal

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"]
  }'

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"
}

JSON

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

JSON

{
  "error": "Contact not found"
}

JSON

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

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ů stáhnout všechny odpovídající kontakty jako soubor.

Parametry dotazu

pageintegervýchozí: 1

Stránka, kterou chcete načíst.

limitintegervýchozí: 10

Počet kontaktů na stránce, od 1 do 100.

searchstring

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

audience_idstring

Jen kontakty v tomto seznamu kontaktů (aud_…).

unsubscribedboolean

true, nebo false. Jen kontakty s tímto stavem odhlášení.

filter[tag]string

Jen kontakty s tímto štítkem. Pokud chcete kontakty s kterýmkoli z několika štítků, oddělte je čárkami. Funguje i tag.

filter[score][gte], filter[score][lte]integer

Jen kontakty se skóre alespoň, nebo nejvýše této hodnoty.

sortstringvýchozí: created_at

email, first_name, last_name, name, audiences, score, created_at nebo updated_at.

orderstringvýchozí: desc

asc, nebo desc. U tohoto endpointu je order směr řazení, ne klíč řazení.

matchstringvýchozí: all

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í.

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ěď

dataobject[]

Kontakty na této stránce, každý s audiences ve tvaru id, name a subscribed. Viz Načtení kontaktu.

total_recordsinteger

Počet odpovídajících kontaktů napříč všemi stránkami.

next_page_urlstring | null

Cesta k další stránce s vašimi filtry, nebo null. Viz Stránkování.

previous_page_urlstring | null

Cesta k předchozí stránce, nebo null.

GET/contacts

JavaScript

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

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

Python

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

contacts = client.contacts.list()

PHP

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

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

Ruby

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

contacts = client.contacts.list

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

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

Rust

use emailit::Emailit;

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

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

Java

import com.emailit.*;

EmailitClient emailit = new EmailitClient("your_api_key");

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

using Emailit;

var emailit = new EmailitClient("your_api_key");

var contacts = emailit.Contacts.List();

PHP

use Emailit\Laravel\Facades\Emailit;

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

Terminal

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

Terminal

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"

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
}

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.
`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

actionstringpovinné

delete, add_to_audience, remove_from_audience, unsubscribe nebo resubscribe.

idsstring[]povinné

ID kontaktů (con_…), od 1 do 100. E-mailové adresy se tu nepřijímají. Duplicity se ignorují.

audience_idstring

ID seznamu kontaktů. Povinné pro add_to_audience a remove_from_audience.

Odpověď

objectstring

Vždy contact_bulk.

actionstring

Akce, která proběhla.

processedinteger

Kolik kontaktů se zpracovalo.

idsstring[]

ID zpracovaných kontaktů.

POST/contacts/bulk

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

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

$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

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)

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

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

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());

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);

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();

Terminal

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"}'

JSON

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

JSON

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

JSON

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

JSON

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

Přidání štítků kontaktu

Přidá kontaktu štítky. Štítky, které už kontakt má, zůstanou beze změny. Vyžaduje API klíč s oprávněním full.

Štítky se oříznou o mezery na začátku a na konci, ukládají se malými písmeny se sloučenými vícenásobnými mezerami a mohou mít až 64 znaků. Když je aspoň jeden štítek nový, Emailit vyvolá událost contact.updated s novými štítky v tags a starými v previous.tags, která spouští automatizace se spouštěčem Tag added. Viz Štítky a skóre kontaktů.

POST/contacts/{id}/tags

Parametry v cestě

idstringpovinné

ID kontaktu (con_…), nebo e-mailová adresa kontaktu zakódovaná pro URL.

Parametry v těle požadavku

tagsstring[]povinné

Štítky, které se mají přidat, nejvýše 50.

Odpověď

dataobject

id a email kontaktu, všechny jeho štítky v tags po změně a changed, tedy štítky, které se přidaly.

messagestring

Například 1 tag added. nebo No tags changed.

Pokud je štítek prázdný nebo delší než 64 znaků, vrací 400, pro neexistující kontakt 404.

JSON

{
  "data": {
    "id": "con_2kq8Vt4xLm7Rz",
    "email": "ada@example.com",
    "tags": ["customer", "vip", "webinar-2026"],
    "changed": ["customer", "webinar-2026"]
  },
  "message": "2 tags added."
}

POST/contacts/{id}/tags

Terminal

curl -X POST https://api.emailit.com/v2/contacts/ada@example.com/tags \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"tags": ["customer", "webinar-2026"]}'

JavaScript

const res = await fetch('https://api.emailit.com/v2/contacts/ada@example.com/tags', {
  method: 'POST',
  headers: { Authorization: `Bearer ${process.env.EMAILIT_API_KEY}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({"tags": ["customer", "webinar-2026"]}),
});
const result = await res.json();

Python

import os, requests

r = requests.post(
    "https://api.emailit.com/v2/contacts/ada@example.com/tags",
    headers={"Authorization": f"Bearer {os.environ['EMAILIT_API_KEY']}"},
    json={"tags": ["customer", "webinar-2026"]},
)
result = r.json()

PHP

$client = new GuzzleHttp\Client(['base_uri' => 'https://api.emailit.com/v2/']);

$response = $client->post('contacts/ada@example.com/tags', [
    'headers' => ['Authorization' => 'Bearer ' . getenv('EMAILIT_API_KEY')],
    'json' => ['tags' => ['customer', 'webinar-2026']],
]);
$result = json_decode($response->getBody(), true);

Odebrání štítků kontaktu

Odebere kontaktu štítky. Štítky, které kontakt nemá, se ignorují. Vyžaduje API klíč s oprávněním full.

Když se odebere aspoň jeden štítek, Emailit vyvolá událost contact.updated s previous.tags, která spouští automatizace se spouštěčem Tag removed. Viz Štítky a skóre kontaktů.

DELETE/contacts/{id}/tags

Parametry v cestě

idstringpovinné

ID kontaktu (con_…), nebo e-mailová adresa kontaktu zakódovaná pro URL.

Parametry v těle požadavku

tagsstring[]povinné

Štítky, které se mají odebrat, nejvýše 50. Porovnávají se malými písmeny.

Odpověď

dataobject

id a email kontaktu, jeho zbývající štítky v tags a changed, tedy štítky, které se odebraly.

messagestring

Například 1 tag removed. nebo No tags changed.

Pokud kontakt neexistuje, vrací 404.

DELETE/contacts/{id}/tags

Terminal

curl -X DELETE https://api.emailit.com/v2/contacts/con_2kq8Vt4xLm7Rz/tags \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"tags": ["trial"]}'

JavaScript

const res = await fetch('https://api.emailit.com/v2/contacts/con_2kq8Vt4xLm7Rz/tags', {
  method: 'DELETE',
  headers: { Authorization: `Bearer ${process.env.EMAILIT_API_KEY}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({"tags": ["trial"]}),
});
const result = await res.json();

Python

import os, requests

r = requests.delete(
    "https://api.emailit.com/v2/contacts/con_2kq8Vt4xLm7Rz/tags",
    headers={"Authorization": f"Bearer {os.environ['EMAILIT_API_KEY']}"},
    json={"tags": ["trial"]},
)
result = r.json()

PHP

$client = new GuzzleHttp\Client(['base_uri' => 'https://api.emailit.com/v2/']);

$response = $client->delete('contacts/con_2kq8Vt4xLm7Rz/tags', [
    'headers' => ['Authorization' => 'Bearer ' . getenv('EMAILIT_API_KEY')],
    'json' => ['tags' => ['trial']],
]);
$result = json_decode($response->getBody(), true);

Vrátí štítky použité u kontaktů ve workspace, seřazené abecedně, a u každého počet kontaktů, které ho mají. Vyžaduje API klíč s oprávněním full. Pokud chcete vypsat kontakty s určitým štítkem, použijte Výpis kontaktů s filter[tag].

GET/contacts/tags

Parametry dotazu

searchstring

Jen štítky, které obsahují tento text.

limitintegervýchozí: 200

Kolik štítků se má vrátit, od 1 do 1 000.

Odpověď

dataobject[]

Každý štítek ve tvaru { "object": "tag", "tag": "customer", "contacts": 42 }.

GET/contacts/tags

Terminal

curl "https://api.emailit.com/v2/contacts/tags?search=web" \
  -H "Authorization: Bearer $EMAILIT_API_KEY"

JavaScript

const res = await fetch('https://api.emailit.com/v2/contacts/tags?search=web', {
  method: 'GET',
  headers: { Authorization: `Bearer ${process.env.EMAILIT_API_KEY}` },
});
const result = await res.json();

Python

import os, requests

r = requests.get(
    "https://api.emailit.com/v2/contacts/tags?search=web",
    headers={"Authorization": f"Bearer {os.environ['EMAILIT_API_KEY']}"},
)
result = r.json()

PHP

$client = new GuzzleHttp\Client(['base_uri' => 'https://api.emailit.com/v2/']);

$response = $client->get('contacts/tags?search=web', [
    'headers' => ['Authorization' => 'Bearer ' . getenv('EMAILIT_API_KEY')],
]);
$result = json_decode($response->getBody(), true);

Změna skóre kontaktu

Přičte ke skóre kontaktu body, odečte je, nebo skóre nastaví. Vyžaduje API klíč s oprávněním full.

Změna je atomická, takže se souběžná volání navzájem nepřepíšou. Skóre začíná na 0, může být záporné a drží se v rozsahu ±1 000 000 000. Když se skóre změní, Emailit vyvolá událost contact.updated se score a previous.score, která spouští automatizace se spouštěčem Score changed. Viz Štítky a skóre kontaktů.

POST/contacts/{id}/score

Parametry v cestě

idstringpovinné

ID kontaktu (con_…), nebo e-mailová adresa kontaktu zakódovaná pro URL.

Parametry v těle požadavku

operationstringvýchozí: add

add, subtract, nebo set.

valueintegerpovinné

Body, které se mají přičíst nebo odečíst, nebo nové skóre.

Odpověď

dataobject

id a email kontaktu, nové skóre v score a předchozí v previous_score.

messagestring

Například Score is now 55.

Pokud je operation nebo value neplatné, vrací 400, pro neexistující kontakt 404.

JSON

{
  "data": { "id": "con_2kq8Vt4xLm7Rz", "email": "ada@example.com", "score": 55, "previous_score": 45 },
  "message": "Score is now 55."
}

POST/contacts/{id}/score

Terminal

curl -X POST https://api.emailit.com/v2/contacts/con_2kq8Vt4xLm7Rz/score \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"operation": "add", "value": 10}'

JavaScript

const res = await fetch('https://api.emailit.com/v2/contacts/con_2kq8Vt4xLm7Rz/score', {
  method: 'POST',
  headers: { Authorization: `Bearer ${process.env.EMAILIT_API_KEY}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({"operation": "add", "value": 10}),
});
const result = await res.json();

Python

import os, requests

r = requests.post(
    "https://api.emailit.com/v2/contacts/con_2kq8Vt4xLm7Rz/score",
    headers={"Authorization": f"Bearer {os.environ['EMAILIT_API_KEY']}"},
    json={"operation": "add", "value": 10},
)
result = r.json()

PHP

$client = new GuzzleHttp\Client(['base_uri' => 'https://api.emailit.com/v2/']);

$response = $client->post('contacts/con_2kq8Vt4xLm7Rz/score', [
    'headers' => ['Authorization' => 'Bearer ' . getenv('EMAILIT_API_KEY')],
    'json' => ['operation' => 'add', 'value' => 10],
]);
$result = json_decode($response->getBody(), true);

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ů, 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

formatstringvýchozí: csv

csv, nebo xlsx.

search, audience_id, unsubscribed, sort, order, match, key.conditionstring

Stejné parametry jako u endpointu Výpis kontaktů.

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é `;` .
`tags`	Štítky kontaktu, oddělené `;` .
`score`	Skóre kontaktu.
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.

GET/contacts/export

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

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

$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

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)

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

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

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")));

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);

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);

Terminal

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

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

JSON

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

JSON

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

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 a nastavte unsubscribed: true, nebo adresu přidejte na seznam blokovaných adres. Vyvolá subscriber.deleted pro každé členství a potom contact.deleted.

Parametry v cestě

idstringpovinné

ID kontaktu (con_…), nebo e-mailová adresa kontaktu zakódovaná pro URL.

Odpověď

objectstring

Vždy contact.

idstring

ID smazaného kontaktu.

emailstring

E-mailová adresa kontaktu.

deletedboolean

Vždy true.

DELETE/contacts/{id}

JavaScript

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

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

Python

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

client.contacts.delete("con_4Kt4ZXloQR8WGcMsYx8PFCUjokM")

PHP

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

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

Ruby

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

client.contacts.delete("con_4Kt4ZXloQR8WGcMsYx8PFCUjokM")

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

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

Rust

use emailit::Emailit;

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

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

Java

import com.emailit.*;

EmailitClient emailit = new EmailitClient("your_api_key");

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

using Emailit;

var emailit = new EmailitClient("your_api_key");

emailit.Contacts.Delete("con_4Kt4ZXloQR8WGcMsYx8PFCUjokM");

PHP

use Emailit\Laravel\Facades\Emailit;

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

Terminal

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

JSON

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

JSON

{
  "error": "Contact not found"
}

Vytvoření kontaktu

Parametry v těle požadavku

Odpověď

Načtení kontaktu

Parametry v cestě

Odpověď

Úprava kontaktu

Parametry v cestě

Parametry v těle požadavku

Odpověď

Výpis kontaktů

Parametry dotazu

Filtry

Odpověď

Hromadná úprava kontaktů

Parametry v těle požadavku

Odpověď

Přidání štítků kontaktu

Parametry v cestě

Parametry v těle požadavku

Odpověď

Odebrání štítků kontaktu

Parametry v cestě

Parametry v těle požadavku

Odpověď

Výpis štítků

Parametry dotazu

Odpověď

Změna skóre kontaktu

Parametry v cestě

Parametry v těle požadavku

Odpověď

Export kontaktů

Parametry dotazu

Odpověď

Smazání kontaktu

Parametry v cestě

Odpověď