Gyors kezdés

Base URL

https://echo.uptools.io/public/v1

Ugyanezt a címet mutatja a felületen az Integrációk menü API oldala a Base URL mellett. A példák két shell-változót használnak:

export ECHO_API=https://echo.uptools.io/public/v1
export ECHO_TOKEN=upm_...   # az API-tokened, lásd Hitelesítés

Az első kérés

Hozz létre egy tokent az Integrációk, API, Új token létrehozása úton (Hitelesítés), majd kérdezd le, hány aktív feliratkozód van:

curl -H "Authorization: Bearer $ECHO_TOKEN" "$ECHO_API/subscribers/count"

HTTP/1.1 200 OK
Content-Type: application/json
X-Ratelimit-Limit: 120
X-Ratelimit-Remaining: 119

{"data":{"total":4712}}

Egy feliratkozó felvétele (Teljes hozzáférés szintű token kell hozzá):

curl -X POST "$ECHO_API/subscribers" \
  -H "Authorization: Bearer $ECHO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"email":"[email protected]","fields":{"name":"Lilla","city":"Szeged"}}'

A válasz 201 Created az új feliratkozóval, vagy 200 OK, ha a cím már szerepelt a listán. A részletek a Feliratkozók oldalon vannak.

A kérések formátuma

Minden kéréshez kell az Authorization: Bearer <token> fejléc.
A kérés törzse csak JSON lehet: küldd a Content-Type: application/json fejlécet. Másra 415 unsupported_media_type a válasz.
A törzs egyetlen JSON-objektum legyen. A hibás JSON vagy bármi más, ami nem egyetlen objektum, 400 invalid_json választ kap. Az ismeretlen kulcsokat az API 422 validation hibával elutasítja (a kulcsot a fields megnevezi), így egy elírás sem marad észrevétlen.
A törzs legfeljebb 1 MB lehet, importnál legfeljebb 10 MB.
Az Accept-Language: en vagy hu fejléc dönti el a hibaüzenetek nyelvét. Az adatokat (mezőnevek, csoportnevek) az API nem fordítja. Az útmutató példái Accept-Language: en fejléccel futottak.
A szögletes zárójeles paraméterekhez, mint a filter[status], a curl -g kapcsolója kell (vagy URL-kódolás: filter%5Bstatus%5D), különben a curl mintának olvassa a zárójeleket.
Az azonosítók UUID-k. Az API válaszaiban minden időpont UTC szerinti, Z végű RFC 3339 időbélyeg (például 2026-10-22T08:52:08.527488Z). A webhookok üzeneteiben eltolással megadott időpont is lehet (Webhookok), ezért az időpontokat RFC 3339 szerint dolgozd fel.
A JSON-szövegekben a HTML < és > jele \u003c és \u003e formában érkezik. Bármelyik JSON-feldolgozó visszaalakítja őket.

A válaszok formátuma

Egy objektum a data kulcsban érkezik:

{"data":{"id":"257e83a2-d55e-4a8c-b9a4-b3e939c151cc","name":"Webshop vásárlók","created_at":"2026-10-22T08:52:08.269421Z","subscribers":0,"total":0,"open_rate":0,"click_rate":0}}

Egy lista a data kulcsban, a lapozás adatai a meta kulcsban:

{"data":[...],"meta":{"next_cursor":"bzoz","prev_cursor":null,"limit":3,"total":7}}

A sikeres törlés és a tartalom nélküli művelet 204 No Content választ ad, üres törzzsel. A hibáknak saját formátumuk van, lásd Hibák és korlátok.

Lapozás

A listák a limit paramétert fogadják (1 és 100 között, alapból 25), a kurzorokat a meta adja vissza:

Kulcs	Jelentés
`next_cursor`	Ezt add át `cursor` paraméterként a következő oldalhoz. Az utolsó oldalon `null`.
`prev_cursor`	Ezt add át `cursor` paraméterként az előző oldalhoz. Az első oldalon `null`.
`limit`	A használt oldalméret.
`total`	A találatok száma, ha olcsó volt megszámolni. Hiányozhat.

A kurzorok átlátszatlan szövegek: változtatás nélkül add vissza őket, mindig a cursor paraméterben, akármerre lapozol. Két lista csak előre lapoz: egy feliratkozó tevékenysége és egy munkafolyamat futásai. Ezeknél a prev_cursor mindig null.

A feliratkozólisták a prev_cursor értékét a régebbi before paraméterben is elfogadják, de ez elavult: használd a cursor paramétert.

Példa, a csoportok első, majd második oldala:

curl -g -H "Authorization: Bearer $ECHO_TOKEN" "$ECHO_API/groups?limit=3"
curl -g -H "Authorization: Bearer $ECHO_TOKEN" "$ECHO_API/groups?limit=3&cursor=bzoz"

{"data":[{"id":"26e38149-d391-4215-86e4-92bb883e5910","name":"Új regisztrálók","created_at":"2026-09-20T14:45:00Z","subscribers":427,"total":451,"open_rate":37.55,"click_rate":7.72,"timed_out":false},{"id":"000d6529-0078-40d8-9c29-05cd541c4c2d","name":"VIP vásárlók","created_at":"2026-04-17T12:00:00Z","subscribers":466,"total":495,"open_rate":34.64,"click_rate":7.47,"timed_out":false},{"id":"19e19d19-d3df-4763-965c-d2f4d974e40a","name":"Webinar 2026","created_at":"2026-07-28T09:00:00Z","subscribers":413,"total":438,"open_rate":34.68,"click_rate":8.32,"timed_out":false}],"meta":{"next_cursor":"bzo2","prev_cursor":"bzow","limit":3,"total":7}}

A feliratkozólisták kurzorai titkosítva érkeznek, és idővel érvényüket veszthetik. Ilyenkor egy régi kurzor 422 választ ad fields.cursor hibával: kezdd újra az első oldaltól. A kurzorokat ne tárold sokáig.

Az 1 és 100 közé nem eső limit vagy a hibás kurzor 422 validation hibát ad:

{"error":{"code":"validation","message":"Please check the highlighted fields.","fields":{"limit":"Invalid value."}}}

Idempotencia és újrapróbálás

Az API nem ismer idempotenciakulcs-fejlécet. Az újrapróbálást végpontonként tervezd meg:

Kérés	Biztonságosan ismételhető?
`GET` kérések	Igen.
`POST /subscribers`	Igen: e-mail-cím alapján vesz fel vagy frissít, az ismétlés ugyanazt a feliratkozót frissíti.
`PUT` módosítások (feliratkozó, csoport- vagy szegmensnév, mezőnév, webhook)	Igen: ugyanaz a törzs ugyanazt az eredményt adja.
`POST /subscribers/{id}/groups/{group_id}`	Igen: a meglévő tagság nem változik.
`DELETE`	Az első `204` választ ad, az ismétlés `404 not_found` választ. Időtúllépés után a `404` azt jelenti, hogy a törlés megtörtént.
`POST /groups/{id}/import-subscribers`	Az ismétlés egy második importot indít. Az import a meglévő címeket frissíti, így a feliratkozók nem duplázódnak, de újraküldés előtt nézd meg az első import állapotát.
`POST /campaigns`, `POST /webhooks`, `POST /groups`, `POST /fields`	Nem: az ismétlés második kampányt vagy webhookot hoz létre. Azonos nevű második csoportot vagy mezőt az API elutasít (`409 name_taken`).
`POST /campaigns/{id}/test`	Nem: minden hívás tesztleveleket küld.

429 vagy válasz előtti hálózati hiba után a kérés a Retry-After idő elteltével újraküldhető. A kötegelt kérések nem atomiak: hiba esetén nézd meg egyenként a válaszokat, mielőtt újraküldöd a köteget.