Odběratelé

Přidávejte, upravujte a odebírejte odběratele seznamu kontaktů.

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

POST/audiences/{audience_id}/subscribers
GET/audiences/{audience_id}/subscribers/{id}
POST/audiences/{audience_id}/subscribers/{id}
GET/audiences/{audience_id}/subscribers
POST/audiences/{audience_id}/subscribers/bulk
DEL/audiences/{audience_id}/subscribers/{id}

Přidání odběratele

Přidá kontakt do seznamu kontaktů podle e-mailové adresy.

POST/audiences/{audience_id}/subscribers

Vyžaduje API klíč s oprávněním full. Pokud s tímto e-mailem ještě žádný kontakt neexistuje, Emailit ho vytvoří. Pokud kontakt existuje, jméno, příjmení a vlastní pole, která pošlete, přepíšou jeho aktuální hodnoty. Kontakt, který se ze seznamu odhlásil, se znovu přihlásí a odpověď je 200; kontakt, který už přihlášený je, vrátí 409.

Každý seznam kontaktů může mít tolik odběratelů, kolik povoluje váš tarif; nad tento počet vrátí požadavek 422 s vaším usage. Vyvolá subscriber.created, při opětovném přihlášení subscriber.updated a subscriber.resubscribed.

S double_opt_in dostane osoba e-mail seznamu pro double opt-in a přidá se, až v něm klikne na odkaz, takže odpověď je 202 a odběratel zatím neexistuje.

Parametry v cestě

audience_idstringpovinné

ID seznamu kontaktů (aud_…), nebo jeho název.

Parametry v těle požadavku

emailstringpovinné

E-mailová adresa, kterou chcete přihlásit. Ukládá se malými písmeny.

first_namestring

Jméno kontaktu.

last_namestring

Příjmení kontaktu.

custom_fieldsobject

Hodnoty vlastních polí podle klíče, například {"company": "Analytical Engines"}. Nahradí stávající vlastní pole kontaktu.

double_opt_inbooleanvýchozí: false

Místo okamžitého přihlášení pošle e-mail pro double opt-in. Seznam musí mít double opt-in zapnutý, jinak požadavek vrátí 422. U osoby, která už přihlášená je, vrátí požadavek jako obvykle 409.

send_confirmation_emailbooleanvýchozí: false

Po přihlášení pošle potvrzovací e-mail seznamu, pokud ho má seznam zapnutý.

Odpověď

Vrací 201 s objektem odběratele, nebo 200, pokud se odhlášený kontakt znovu přihlásil. S double_opt_in vrací 202 s object: "subscriber_confirmation", status: "pending", audience_id, contact_id a email. Pokud se e-mail pro double opt-in nepodaří odeslat, požadavek vrátí 422 s polem code, například unverified_domain, nebo insufficient_credits.

POST/audiences/{audience_id}/subscribers

JavaScript

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

const subscriber = await emailit.subscribers.create('aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2', {
  email: 'ada@example.com',
  first_name: 'Ada',
  last_name: 'Lovelace',
});

Python

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

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

PHP

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

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

Ruby

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

subscriber = client.subscribers.create("aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2",
  email: "ada@example.com",
  first_name: "Ada",
  last_name: "Lovelace"
)

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

subscriber, err := client.Subscribers.Create("aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2", &emailit.CreateSubscriberRequest{
  Email:     "ada@example.com",
  FirstName: "Ada",
  LastName:  "Lovelace",
})

Rust

use emailit::Emailit;
use emailit::types::CreateSubscriberParams;

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

let subscriber = emailit.subscribers.create("aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2",
  CreateSubscriberParams::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 subscriber = emailit.subscribers().create("aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2",
  SubscriberCreateParams.builder()
    .setEmail("ada@example.com")
    .setFirstName("Ada")
    .setLastName("Lovelace")
    .build()
);

using Emailit;

var emailit = new EmailitClient("your_api_key");

var subscriber = emailit.Subscribers.Create("aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2", new SubscriberCreateOptions {
  Email = "ada@example.com",
  FirstName = "Ada",
  LastName = "Lovelace",
});

PHP

use Emailit\Laravel\Facades\Emailit;

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

Terminal

curl -X POST https://api.emailit.com/v2/audiences/aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2/subscribers \
  -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" }
  }'

JSON

{
  "object": "subscriber",
  "id": "sub_4KECYl5AwXEy8ezswYRhuddttxo",
  "audience_id": "aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2",
  "contact_id": "con_4K9kQdrXth7am0TPKvPrR5yd2oo",
  "email": "ada@example.com",
  "first_name": "Ada",
  "last_name": "Lovelace",
  "custom_fields": {
    "company": "Analytical Engines"
  },
  "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"
}

JSON

{
  "object": "subscriber_confirmation",
  "status": "pending",
  "audience_id": "aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2",
  "contact_id": "con_4K9kQdrXth7am0TPKvPrR5yd2oo",
  "email": "ada@example.com",
  "message": "A double opt-in email was sent. They join the audience when they click its link."
}

JSON

{
  "error": "Audience not found"
}

JSON

{
  "error": "Contact is already subscribed to this audience",
  "existing": {
    "object": "subscriber",
    "id": "sub_4KECYl5AwXEy8ezswYRhuddttxo",
    "audience_id": "aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2",
    "contact_id": "con_4K9kQdrXth7am0TPKvPrR5yd2oo",
    "email": "ada@example.com",
    "first_name": "Ada",
    "last_name": "Lovelace",
    "custom_fields": { "company": "Analytical Engines" },
    "subscribed": true,
    "subscribed_at": "2026-10-01T10:20:31.000Z",
    "unsubscribed_at": null,
    "created_at": "2026-10-01T10:20:31.000Z",
    "updated_at": "2026-10-01T10:20:31.000Z"
  }
}

JSON

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

Načtení odběratele

Načte členství kontaktu v seznamu kontaktů.

GET/audiences/{audience_id}/subscribers/{id}

Vyžaduje API klíč s oprávněním full. Odběratel propojuje jeden kontakt s jedním seznamem kontaktů. E-mail, jméno a vlastní pole patří kontaktu, kdežto subscribed platí jen pro tento seznam.

Parametry v cestě

audience_idstringpovinné

ID seznamu kontaktů (aud_…), nebo jeho název.

idstringpovinné

ID odběratele (sub_…), nebo e-mailová adresa kontaktu zakódovaná pro URL.

Odpověď

Vrací objekt odběratele.

objectstring

Vždy subscriber.

idstring

ID odběratele.

audience_idstring

ID seznamu kontaktů.

contact_idstring

ID kontaktu.

emailstring

E-mailová adresa kontaktu.

first_namestring | null

Křestní jméno kontaktu.

last_namestring | null

Příjmení kontaktu.

custom_fieldsobject | null

Hodnoty vlastních polí kontaktu.

subscribedboolean

true, pokud je kontakt k odběru tohoto seznamu přihlášený, false, pokud se odhlásil.

subscribed_atstring | null

Kdy se kontakt naposledy přihlásil.

unsubscribed_atstring | null

Kdy se kontakt odhlásil, nebo null.

created_atstring

Kdy kontakt přibyl do seznamu.

updated_atstring

Kdy se členství naposledy změnilo.

GET/audiences/{audience_id}/subscribers/{id}

JavaScript

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

const subscriber = await emailit.subscribers.get('aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2', 'sub_4KECYl5AwXEy8ezswYRhuddttxo');

Python

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

subscriber = client.subscribers.get("aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2", "sub_4KECYl5AwXEy8ezswYRhuddttxo")

PHP

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

$subscriber = $emailit->subscribers()->get('aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2', 'sub_4KECYl5AwXEy8ezswYRhuddttxo');

Ruby

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

subscriber = client.subscribers.get("aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2", "sub_4KECYl5AwXEy8ezswYRhuddttxo")

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

subscriber, err := client.Subscribers.Get("aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2", "sub_4KECYl5AwXEy8ezswYRhuddttxo")

Rust

use emailit::Emailit;

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

let subscriber = emailit.subscribers.get("aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2", "sub_4KECYl5AwXEy8ezswYRhuddttxo").await?;

Java

import com.emailit.*;

EmailitClient emailit = new EmailitClient("your_api_key");

EmailitObject subscriber = emailit.subscribers().get("aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2", "sub_4KECYl5AwXEy8ezswYRhuddttxo");

using Emailit;

var emailit = new EmailitClient("your_api_key");

var subscriber = emailit.Subscribers.Get("aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2", "sub_4KECYl5AwXEy8ezswYRhuddttxo");

PHP

use Emailit\Laravel\Facades\Emailit;

$subscriber = Emailit::subscribers()->get('aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2', 'sub_4KECYl5AwXEy8ezswYRhuddttxo');

Terminal

curl https://api.emailit.com/v2/audiences/aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2/subscribers/sub_4KECYl5AwXEy8ezswYRhuddttxo \
  -H "Authorization: Bearer $EMAILIT_API_KEY"

JSON

{
  "object": "subscriber",
  "id": "sub_4KECYl5AwXEy8ezswYRhuddttxo",
  "audience_id": "aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2",
  "contact_id": "con_4K9kQdrXth7am0TPKvPrR5yd2oo",
  "email": "ada@example.com",
  "first_name": "Ada",
  "last_name": "Lovelace",
  "custom_fields": {
    "company": "Analytical Engines"
  },
  "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"
}

JSON

{
  "error": "Subscriber not found"
}

Úprava odběratele

Změní stav odběratele v seznamu kontaktů, nebo údaje jeho kontaktu.

POST/audiences/{audience_id}/subscribers/{id}

Vyžaduje API klíč s oprávněním full. Pošlete jen pole, která chcete změnit. subscribed platí jen pro tento seznam kontaktů. email, first_name, last_name a custom_fields mění samotný kontakt, takže se změna projeví ve všech seznamech kontaktů, do kterých kontakt patří. Vyvolá událost subscriber.updated.

Parametry v cestě

audience_idstringpovinné

ID seznamu kontaktů (aud_…), nebo jeho název.

idstringpovinné

ID odběratele (sub_…), nebo e-mailová adresa kontaktu zakódovaná pro URL.

Parametry v těle požadavku

subscribedboolean

false kontakt z tohoto seznamu odhlásí, true ho znovu přihlásí. Odběratel v seznamu v obou případech zůstane.

emailstring

Nová e-mailová adresa kontaktu. Ukládá se malými písmeny.

first_namestring

Křestní jméno kontaktu.

last_namestring

Příjmení kontaktu.

custom_fieldsobject

Hodnoty vlastních polí podle klíče. Nahradí stávající vlastní pole kontaktu.

Odpověď

Vrací upravený objekt odběratele. Požadavek, který neobsahuje žádné z těchto polí, vrací 400.

POST/audiences/{audience_id}/subscribers/{id}

JavaScript

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

const subscriber = await emailit.subscribers.update('aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2', 'sub_4KECYl5AwXEy8ezswYRhuddttxo', {
  first_name: 'Augusta',
});

Python

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

subscriber = client.subscribers.update("aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2", "sub_4KECYl5AwXEy8ezswYRhuddttxo", {
  "first_name": "Augusta",
})

PHP

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

$subscriber = $emailit->subscribers()->update('aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2', 'sub_4KECYl5AwXEy8ezswYRhuddttxo', [
  'first_name' => 'Augusta',
]);

Ruby

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

subscriber = client.subscribers.update("aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2", "sub_4KECYl5AwXEy8ezswYRhuddttxo",
  first_name: "Augusta"
)

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

subscriber, err := client.Subscribers.Update("aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2", "sub_4KECYl5AwXEy8ezswYRhuddttxo", &emailit.UpdateSubscriberRequest{
  FirstName: "Augusta",
})

Rust

use emailit::Emailit;
use emailit::types::UpdateSubscriberParams;

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

let subscriber = emailit.subscribers.update("aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2", "sub_4KECYl5AwXEy8ezswYRhuddttxo", UpdateSubscriberParams {
  first_name: Some("Augusta".into()),
  ..Default::default()
}).await?;

Java

import com.emailit.*;
import com.emailit.params.*;

EmailitClient emailit = new EmailitClient("your_api_key");

EmailitObject subscriber = emailit.subscribers().update("aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2", "sub_4KECYl5AwXEy8ezswYRhuddttxo",
  SubscriberUpdateParams.builder()
    .setFirstName("Augusta")
    .build()
);

using Emailit;

var emailit = new EmailitClient("your_api_key");

var subscriber = emailit.Subscribers.Update("aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2", "sub_4KECYl5AwXEy8ezswYRhuddttxo", new SubscriberUpdateOptions {
  FirstName = "Augusta",
});

PHP

use Emailit\Laravel\Facades\Emailit;

$subscriber = Emailit::subscribers()->update('aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2', 'sub_4KECYl5AwXEy8ezswYRhuddttxo', [
  'first_name' => 'Augusta',
]);

Terminal

curl -X POST https://api.emailit.com/v2/audiences/aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2/subscribers/sub_4KECYl5AwXEy8ezswYRhuddttxo \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"first_name": "Augusta"}'

Terminal

curl -X POST https://api.emailit.com/v2/audiences/aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2/subscribers/ada%40example.com \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"subscribed": false}'

JSON

{
  "object": "subscriber",
  "id": "sub_4KECYl5AwXEy8ezswYRhuddttxo",
  "audience_id": "aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2",
  "contact_id": "con_4K9kQdrXth7am0TPKvPrR5yd2oo",
  "email": "ada@example.com",
  "first_name": "Ada",
  "last_name": "Lovelace",
  "custom_fields": {
    "company": "Analytical Engines"
  },
  "subscribed": false,
  "subscribed_at": "2026-10-01T10:20:31.000000Z",
  "unsubscribed_at": "2026-10-02T08:14:55.000000Z",
  "created_at": "2026-10-01T10:20:31.000000Z",
  "updated_at": "2026-10-02T08:14:55.000000Z"
}

JSON

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

JSON

{
  "error": "Subscriber not found"
}

Výpis odběratelů

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

GET/audiences/{audience_id}/subscribers

Vyžaduje API klíč s oprávněním full. Výpis obsahuje i kontakty, které se ze seznamu kontaktů odhlásily, pokud je neodfiltrujete pomocí subscribed=true.

Parametry v cestě

audience_idstringpovinné

ID seznamu kontaktů (aud_…), nebo jeho název.

Parametry dotazu

pageintegervýchozí: 1

Stránka, kterou chcete načíst.

limitintegervýchozí: 25

Počet odběratelů na stránce, od 1 do 100. Funguje i per_page.

subscribedstring

true jen pro přihlášené kontakty, false jen pro odhlášené.

engagementstring

unengaged pro odběratele, kteří se v období nastaveném u seznamu počítají jako neaktivní, engaged pro ostatní. V kombinaci se subscribed=true vynecháte lidi, kteří se už odhlásili.

searchstring

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

matchstringvýchozí: all

all, nebo or. Určuje, jak se kombinují filtry níže.

orderstring

Klíč filtru, podle kterého se řadí.

directionstring

asc, nebo desc.

Filtry

Filtry přidejte ve tvaru key.condition=value, například email.ends_with=@acme.com. Viz Filtrování a řazení.

Klíč	Typ	Poznámky
`email`	string
`first_name`	string
`last_name`	string
`subscribed`	boolean
`subscribed_at`	date	Kdy přihlášení naposledy začalo.
`last_engaged_at`	date	Poslední otevření nebo proklik kontaktu. Prázdné hodnoty se řadí na konec.
`created_at`	date	Kdy kontakt přibyl do seznamu.

Podle každého klíče lze také řadit.

Odpověď

dataobject[]

Objekty odběratelů na této stránce. Ve výpisu má každý z nich navíc last_opened_at, last_clicked_at a last_engaged_at (poslední otevření, poslední proklik a poslední z obojího u kontaktu, nebo null) a unengaged.

total_recordsinteger

Počet odpovídajících odběratelů.

next_page_urlstring | null

Cesta k další stránce, nebo null. Zachovává subscribed a engagement, ale ne vaše ostatní filtry. Viz Stránkování.

previous_page_urlstring | null

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

usageobject

used (počet odběratelů v seznamu), limit (nejvyšší počet, který váš tarif povoluje na jeden seznam, nebo null) a plan.

GET/audiences/{audience_id}/subscribers

JavaScript

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

const subscribers = await emailit.subscribers.list('aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2');

Python

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

subscribers = client.subscribers.list("aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2")

PHP

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

$subscribers = $emailit->subscribers()->list('aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2');

Ruby

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

subscribers = client.subscribers.list("aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2")

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

subscribers, err := client.Subscribers.List("aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2", nil)

Rust

use emailit::Emailit;

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

let subscribers = emailit.subscribers.list("aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2", None).await?;

Java

import com.emailit.*;

EmailitClient emailit = new EmailitClient("your_api_key");

EmailitObject subscribers = emailit.subscribers().list("aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2");

using Emailit;

var emailit = new EmailitClient("your_api_key");

var subscribers = emailit.Subscribers.List("aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2");

PHP

use Emailit\Laravel\Facades\Emailit;

$subscribers = Emailit::subscribers()->list('aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2');

Terminal

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

Terminal

curl -G https://api.emailit.com/v2/audiences/aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2/subscribers \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -d subscribed=true \
  -d limit=100

JSON

{
  "data": [
    {
      "object": "subscriber",
      "id": "sub_4KECYl5AwXEy8ezswYRhuddttxo",
      "audience_id": "aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2",
      "contact_id": "con_4K9kQdrXth7am0TPKvPrR5yd2oo",
      "email": "ada@example.com",
      "first_name": "Ada",
      "last_name": "Lovelace",
      "custom_fields": {
        "company": "Analytical Engines"
      },
      "subscribed": true,
      "subscribed_at": "2026-10-01T10:20:31.000000Z",
      "unsubscribed_at": null,
      "last_opened_at": "2026-10-06T08:14:02.000000Z",
      "last_clicked_at": null,
      "last_engaged_at": "2026-10-06T08:14:02.000000Z",
      "unengaged": false,
      "created_at": "2026-10-01T10:20:31.000000Z",
      "updated_at": "2026-10-01T10:20:31.000000Z"
    },
    {
      "object": "subscriber",
      "id": "sub_4KnmYprkoMRytdkm3tAHIfPW0Vh",
      "audience_id": "aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2",
      "contact_id": "con_4KiXIs4xLTcJIAHnKJaLcnMZYh7",
      "email": "grace@example.com",
      "first_name": "Grace",
      "last_name": "Hopper",
      "custom_fields": null,
      "subscribed": false,
      "subscribed_at": "2026-09-28T07:55:02.000000Z",
      "unsubscribed_at": "2026-09-30T18:11:40.000000Z",
      "last_opened_at": null,
      "last_clicked_at": null,
      "last_engaged_at": null,
      "unengaged": false,
      "created_at": "2026-09-28T07:55:02.000000Z",
      "updated_at": "2026-09-30T18:11:40.000000Z"
    }
  ],
  "total_records": 2,
  "next_page_url": null,
  "previous_page_url": null,
  "usage": {
    "used": 2,
    "limit": 50000,
    "plan": "pro"
  }
}

JSON

{
  "error": "Audience not found"
}

Hromadná úprava odběratelů

Přihlásí, odhlásí nebo odebere mnoho odběratelů jednoho seznamu kontaktů.

POST/audiences/{audience_id}/subscribers/bulk

Vyžaduje API klíč s oprávněním full. Odběratele vyberte podle ids, nebo nastavte all_matching a akce se provede u všech, kdo odpovídají filtrům, nejvýše u 10 000 lidí. Každá změna vyvolá stejnou událost jako změna jednoho odběratele: subscriber.updated při přihlášení a odhlášení, subscriber.deleted při smazání. Odhlášení ponechá lidi v seznamu se subscribed: false; smazání odebere jejich členství a kontakty ponechá. Viz Hromadné akce.

Parametry v cestě

audience_idstringpovinné

ID seznamu kontaktů (aud_…), nebo jeho název.

Parametry v těle požadavku

actionstringpovinné

subscribe, unsubscribe nebo delete.

idsstring[]

ID odběratelů (sub_…), nejvýše 1 000. Všechna musí patřit do seznamu, jinak se nic nezmění a požadavek vrátí 404 s chybějícími ID v poli missing.

all_matchingbooleanvýchozí: false

Místo ids provede akci u všech odběratelů, kteří odpovídají filtrům níže. Víc než 10 000 shod vrátí 422.

engagementstring

S all_matching: unengaged, nebo engaged. Viz Neaktivní kontakty.

subscribedboolean

S all_matching: jen přihlášení (true), nebo jen odhlášení (false) lidé.

searchstring

S all_matching: hledá v e-mailové adrese, křestním jménu nebo příjmení bez ohledu na velikost písmen.

Odpověď

objectstring

Vždy subscriber_bulk.

actionstring

Akce, kterou jste poslali.

audience_idstring

ID seznamu kontaktů.

processedinteger

Kolik odběratelů bylo vybráno.

changedinteger

Kolik se jich změnilo. Přihlášení někoho, kdo už přihlášený je, se nepočítá.

POST/audiences/{audience_id}/subscribers/bulk

JavaScript

const response = await fetch('https://api.emailit.com/v2/audiences/aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2/subscribers/bulk', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer your_api_key',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    action: 'unsubscribe',
    all_matching: true,
    engagement: 'unengaged',
    subscribed: true
  })
});

const { changed } = await response.json();

Terminal

curl -X POST https://api.emailit.com/v2/audiences/aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2/subscribers/bulk \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"action": "unsubscribe", "all_matching": true, "engagement": "unengaged", "subscribed": true}'

JSON

{
  "object": "subscriber_bulk",
  "action": "unsubscribe",
  "audience_id": "aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2",
  "processed": 212,
  "changed": 212
}

JSON

{
  "error": "One or more subscribers were not found",
  "missing": ["sub_4KnmYprkoMRytdkm3tAHIfPW0Vh"]
}

JSON

{
  "error": "More than 10000 subscribers match. Narrow the filter and try again."
}

Smazání odběratele

Odebere kontakt ze seznamu kontaktů.

DELETE/audiences/{audience_id}/subscribers/{id}

Vyžaduje API klíč s oprávněním full. Samotný kontakt se nesmaže a zůstane ve svých ostatních seznamech. Pokud si chcete ponechat záznam o tom, že se někdo odhlásil, raději ho odhlaste pomocí subscribed: false. Vyvolá událost subscriber.deleted.

Parametry v cestě

audience_idstringpovinné

ID seznamu kontaktů (aud_…), nebo jeho název.

idstringpovinné

ID odběratele (sub_…), nebo e-mailová adresa kontaktu zakódovaná do URL.

Odpověď

objectstring

Vždy subscriber.

idstring

ID smazaného odběratele.

audience_idstring

ID seznamu kontaktů.

contact_idstring

ID kontaktu.

emailstring

E-mailová adresa kontaktu.

deletedboolean

Vždy true.

DELETE/audiences/{audience_id}/subscribers/{id}

JavaScript

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

await emailit.subscribers.delete('aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2', 'sub_4KECYl5AwXEy8ezswYRhuddttxo');

Python

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

client.subscribers.delete("aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2", "sub_4KECYl5AwXEy8ezswYRhuddttxo")

PHP

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

$emailit->subscribers()->delete('aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2', 'sub_4KECYl5AwXEy8ezswYRhuddttxo');

Ruby

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

client.subscribers.delete("aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2", "sub_4KECYl5AwXEy8ezswYRhuddttxo")

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

err := client.Subscribers.Delete("aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2", "sub_4KECYl5AwXEy8ezswYRhuddttxo")

Rust

use emailit::Emailit;

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

emailit.subscribers.delete("aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2", "sub_4KECYl5AwXEy8ezswYRhuddttxo").await?;

Java

import com.emailit.*;

EmailitClient emailit = new EmailitClient("your_api_key");

emailit.subscribers().delete("aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2", "sub_4KECYl5AwXEy8ezswYRhuddttxo");

using Emailit;

var emailit = new EmailitClient("your_api_key");

emailit.Subscribers.Delete("aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2", "sub_4KECYl5AwXEy8ezswYRhuddttxo");

PHP

use Emailit\Laravel\Facades\Emailit;

Emailit::subscribers()->delete('aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2', 'sub_4KECYl5AwXEy8ezswYRhuddttxo');

Terminal

curl -X DELETE https://api.emailit.com/v2/audiences/aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2/subscribers/sub_4KECYl5AwXEy8ezswYRhuddttxo \
  -H "Authorization: Bearer $EMAILIT_API_KEY"

JSON

{
  "object": "subscriber",
  "id": "sub_4KECYl5AwXEy8ezswYRhuddttxo",
  "audience_id": "aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2",
  "contact_id": "con_4K9kQdrXth7am0TPKvPrR5yd2oo",
  "email": "ada@example.com",
  "deleted": true
}

JSON

{
  "error": "Subscriber not found"
}