Importálás API-val

Egyszerre néhány feliratkozóhoz (feliratkozás, vásárlás) a POST /subscribers való. Egy egész listához a tömeges import: a háttérben fut, pontosan úgy, mint a felületen a fájlimport, és megjelenik a Feliratkozók menü Előzmények fülén.

Az import indítása

A POST /groups/{id}/import-subscribers 1-50 000 feliratkozót importál egy csoportba. Feliratkozók: kezelés jog kell hozzá.

Kulcs	Jelentés
subscribers	A sorok. Minden sor egy objektum email (kötelező) és fields (értékek mezőkulcs szerint) kulccsal. Más kulcs nem lehet benne.

curl -X POST "$ECHO_API/groups/257e83a2-d55e-4a8c-b9a4-b3e939c151cc/import-subscribers" \
  -H "Authorization: Bearer $ECHO_TOKEN" -H "Content-Type: application/json" \
  -d '{"subscribers":[
        {"email":"[email protected]","fields":{"name":"Bence","city":"Győr"}},
        {"email":"[email protected]","fields":{"name":"Réka","rendelesek_szama":5}},
        {"email":"hibas-cim"}
      ]}'

HTTP/1.1 202 Accepted
Content-Type: application/json
X-Ratelimit-Limit: 5
X-Ratelimit-Remaining: 4

{"data":{"import_id":"df745729-be25-495c-a5b1-8a070dbd18cb"}}

Ennek a válasznak a sebességkorlát-fejlécei az importkeretet mutatják (percenként 5), lásd Hibák és korlátok.

Bármelyik sorban használt mezőkulcsnak léteznie kell a munkaterületen, különben semmi sem importálódik:

{"error":{"code":"validation","message":"Please check the highlighted fields.","fields":{"fields.kedvenc_szin":"Unknown field."}}}

Ismeretlen csoportra a válasz 404 not_found; üres listára vagy 50 000-nél több sorra 422 a fields.subscribers kulccsal.

Az import követése

A GET /subscribers/import/{import_id} (Feliratkozók: megtekintés) mutatja az import haladását és eredményét. Kérdezd le néhány másodpercenként, amíg a status értéke done, failed vagy canceled nem lesz.

curl -H "Authorization: Bearer $ECHO_TOKEN" "$ECHO_API/subscribers/import/df745729-be25-495c-a5b1-8a070dbd18cb"

{"data":{"id":"df745729-be25-495c-a5b1-8a070dbd18cb","kind":"csv","status":"done","filename":"api-import.csv","size_bytes":115,"encoding":"utf-8","delimiter":",","has_header":true,"preview":{"headers":[],"rows":[],"columns":0},"mapping":["email","city","name","rendelesek_szama"],"groups":[{"id":"257e83a2-d55e-4a8c-b9a4-b3e939c151cc","name":"Webshop vásárlók"}],"start_automations":false,"processed_rows":3,"added":2,"updated":0,"failed":1,"error":"","created_at":"2026-10-22T08:52:08.576581Z","started_at":"2026-10-22T08:52:08.759366Z","finished_at":"2026-10-22T08:52:08.810755Z","failed_rows":[{"row":3,"email":"hibas-cim","reason":"invalid_email","detail":""}]}}

Kulcs	Jelentés
status	queued (egy korábbi importra vár), processing, done, failed vagy canceled.
processed_rows	Az eddig feldolgozott sorok.
added, updated, failed	Új feliratkozók, frissített feliratkozók, kimaradt sorok.
error	parse_error vagy internal, ha az egész import meghiúsult, egyébként üres.
mapping	Az oszlopok: email, aztán a használt mezőkulcsok (ábécérendben).
start_automations	API-s importnál mindig false.
failed_rows	Az első 100 kimaradt sor: row (a sor helye a subscribers tömbben, 1-től), email úgy, ahogy elküldted (üres, ha hiányzott), reason és detail (a mező, ha egy értéket utasított el).

Az API-s import egy api-import.csv nevű CSV-ként tárolódik, ezért a kind, a filename, az encoding, a delimiter és a has_header ezt a fájlt írja le. A failed minden kimaradt sort megszámol, a failed_rows az első 100-at sorolja fel. A reason értéke missing_email, invalid_email, duplicate, role_address, short_gmail, suppressed, invalid_number, invalid_date, value_too_long vagy invalid_text. Ugyanezeket a sorokat a felületen az import eredményoldala is mutatja (Előzmények fül, Megtekintés).

Hogyan kezeli a sorokat

• Az új címek import forrású, active feliratkozók lesznek a csoportban. Az importált feliratkozók nem kapnak megerősítő levelet, ezért csak olyanokat importálj, akik hozzájárultak a leveleidhez.
• A meglévő címek frissülnek, és bekerülnek a csoportba; az állapotuk nem változik, a leiratkozott leiratkozott marad.
• Az üres érték nem törli a tárolt értéket.
• A sorok ugyanazokból az okokból maradnak ki, mint a felületen: érvénytelen vagy hiányzó cím, szerepkör-cím, tiltólistán lévő cím, a listában kétszer szereplő cím, vagy a mező típusához nem illő érték (szám mezőbe szám, dátumhoz YYYY-MM-DD).
• Az import nem indít automatizálást.
• Egy munkaterületen egyszerre egy import fut, a második queued állapotban vár.
• Amikor az import végez, a munkaterület értesítési csengője jelzi; API-s importról e-mail-értesítés nem megy.

Korlátok

Korlát	Érték
Sorok egy kérésben	1-50 000
A kérés törzse	10 MB (fölötte 413 too_large)
Import tokenenként	Percenként 5, a percenkénti 120 kérésen felül