Stránkování

Endpointy pro výpisy vracejí výsledky po stránkách. Většina z nich používá čísla stránek s page a limit, šablony a automatizace používají page a per_page a endpointy DMARC používají limit a offset. Tato stránka vysvětluje jednotlivé formáty, časová okna výpisů e-mailů a událostí a jak projít všechny stránky.

Page a limit

Většina endpointů pro výpisy přijímá dva parametry dotazu:

Výchozí velikost stránky závisí na endpointu:

Výpis odběratelů přijímá také per_page jako alias pro limit.

Odpověď

{
  "data": [
    { "object": "domain", "id": "dom_4K468YrjOkR1wwdhqiO0G9XEUey", "name": "acme.com" }
  ],
  "next_page_url": "/v2/domains?page=3&limit=10",
  "previous_page_url": "/v2/domains?page=1&limit=10"
}

URL stránek jsou cesty, ne úplné URL, a u většiny endpointů obsahují jen page a limit, ne vaše filtry. Další stránku načtete tak, že zopakujete vlastní požadavek s page zvýšeným o jedna, a skončíte, když je next_page_url null.

Některé výpisy přidávají vedle data další pole:

Page a per_page

Výpis šablon, Výpis automatizací a Výpis spuštění používají místo limit parametr per_page a místo URL stránek vracejí počty stránek:

{
  "data": [],
  "total_records": 42,
  "per_page": 25,
  "current_page": 2,
  "total_pages": 2
}

Načítejte další stránky, dokud je current_page menší než total_pages.

Limit a offset

Endpointy DMARC místo počítání stránek přeskakují určitý počet řádků:

Výpis souhrnných reportů a Výpis forenzních reportů vracejí celkový počet, takže víte, kdy skončit:

{
  "data": [],
  "meta": { "total": 130, "limit": 25, "offset": 50 }
}

Endpointy s rozpady vracejí meta jen s limit a offset. Skončete, když má stránka méně řádků než limit.

Časová okna

Dva výpisy se dívají jen na nedávná data, pokud si nevyžádáte víc:

• E-maily. Výpis e-mailů ve výchozím stavu vrací e-maily za posledních 14 dní. Pokud chcete hledat dál do minulosti, předejte date_from (a volitelně date_to) jako datum, například 2026-08-01. Filtry created_at okno nerozšiřují, proto použijte date_from.
• Události. Výpis událostí ve výchozím stavu vrací události za poslední dva dny. Jakýkoli filtr created_at, například created_at.after=2026-09-01, toto okno nahradí. Výpis navíc končí na offsetu 2 500: stránka, která začíná za 2 500. událostí, vrátí 422 s kódem events_offset_too_large. Ke starším událostem se dostanete tak, že výsledky zúžíte filtry type nebo created_at.

Načtěte všechny stránky

Opakujte požadavky, dokud API neoznámí, že další stránka není. Tyto příklady načtou všechny kontakty v seznamu kontaktů:

page=1
while : ; do
  response=$(curl -s -G https://api.emailit.com/v2/contacts \
    -H "Authorization: Bearer $EMAILIT_API_KEY" \
    --data-urlencode "audience_id=aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2" \
    --data-urlencode "limit=100" \
    --data-urlencode "page=$page")

  echo "$response" | jq -c '.data[]'

  [ "$(echo "$response" | jq -r '.next_page_url')" = "null" ] && break
  page=$((page + 1))
done

async function* listAll(path, params = {}) {
  for (let page = 1; ; page++) {
    const query = new URLSearchParams({ ...params, limit: '100', page: String(page) });
    const response = await fetch(`https://api.emailit.com/v2${path}?${query}`, {
      headers: { Authorization: `Bearer ${process.env.EMAILIT_API_KEY}` },
    });
    if (!response.ok) throw new Error(`Emailit ${response.status}`);

    const body = await response.json();
    yield* body.data;
    if (!body.next_page_url) return;
  }
}

for await (const contact of listAll('/contacts', { audience_id: 'aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2' })) {
  console.log(contact.email);
}

import os
import requests

def list_all(path, params=None):
    session = requests.Session()
    session.headers["Authorization"] = f"Bearer {os.environ['EMAILIT_API_KEY']}"
    page = 1
    while True:
        response = session.get(
            f"https://api.emailit.com/v2{path}",
            params={**(params or {}), "limit": 100, "page": page},
            timeout=30,
        )
        response.raise_for_status()
        body = response.json()
        yield from body["data"]
        if not body["next_page_url"]:
            return
        page += 1

for contact in list_all("/contacts", {"audience_id": "aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2"}):
    print(contact["email"])

Konzistentní výsledky

Stránky se počítají v okamžiku, kdy si je vyžádáte. Pokud se během procházení výpisu řazeného od nejnovějších vytvoří nebo smažou objekty, mohou se objekty mezi stránkami posunout, takže některý uvidíte dvakrát, nebo vám některý unikne. Pro stabilní export výpisu, který stále roste, řaďte od nejstarších přes order=created_at&direction=asc (u kontaktů a blokovaných adres přes sort=created_at&order=asc) a přeskakujte ID, která už jste viděli.

Související