Feliratkozók
Olvasáshoz Feliratkozók: megtekintés, íráshoz Feliratkozók: kezelés jog kell (Hitelesítés).
A feliratkozó objektum
Szekció neve “A feliratkozó objektum”{ "id": "d5f0b4b1-b59d-40eb-b2e0-74857893a055", "status": "unconfirmed", "source": "api", "fields": {"city": "Szeged", "last_name": "Farkas", "name": "Lilla", "rendelesek_szama": 3}, "groups": [{"id": "257e83a2-d55e-4a8c-b9a4-b3e939c151cc", "name": "Webshop vásárlók"}], "signup_ip": "203.0.113.25", "optin_ip": null, "subscribed_at": "2026-10-22T08:52:08.527488Z", "opted_in_at": null, "unsubscribed_at": null, "timezone": null, "location_country": null, "location_city": null, "sent": 0, "opens": 0, "clicks": 0, "open_rate": 0, "click_rate": 0, "created_at": "2026-10-22T08:52:08.527488Z", "updated_at": "2026-10-22T08:52:08.527488Z"}| Kulcs | Jelentés |
|---|---|
status |
active, unsubscribed, unconfirmed (dupla megerősítésre vár), bounced vagy junk (spamjelentés). |
source |
Honnan került be: manual, import, api, form, landing_page, integration vagy preference_center. |
fields |
Az értékek mezőkulcs szerint (mezők). A szám mezők számok, a dátum mezők YYYY-MM-DD szövegek. Az üres mezők kimaradnak. |
groups |
A csoportok, amelyeknek a feliratkozó tagja. |
signup_ip, optin_ip |
A feliratkozási és a megerősítési IP-cím, ha ismert. |
sent, opens, clicks, open_rate, click_rate |
Levélstatisztika; az arányok százalékok. |
timezone, location_country, location_city |
A feliratkozó tevékenységéből észlelve, ha ismert. |
Feliratkozók listázása
Szekció neve “Feliratkozók listázása”GET /subscribers
| Paraméter | Jelentés |
|---|---|
filter[status] |
active (alapértelmezett), unsubscribed, unconfirmed, bounced, junk vagy all. |
filter[group] |
Csoportazonosító: csak a csoport tagjai. |
limit, cursor |
Lapozás, a legújabb feliratkozóval kezdve (Lapozás). |
curl -g -H "Authorization: Bearer $ECHO_TOKEN" \ "$ECHO_API/subscribers?filter[group]=257e83a2-d55e-4a8c-b9a4-b3e939c151cc&limit=1"{"data":[{"id":"98cc16c4-cb25-4ec6-8dbe-9704c4e198c4","email":"[email protected]","status":"active","source":"import","fields":{"name":"Réka","rendelesek_szama":5},"groups":[{"id":"257e83a2-d55e-4a8c-b9a4-b3e939c151cc","name":"Webshop vásárlók"}],"signup_ip":null,"optin_ip":null,"subscribed_at":"2026-10-22T08:52:08.762873Z","opted_in_at":null,"unsubscribed_at":null,"timezone":null,"location_country":null,"location_city":null,"sent":0,"opens":0,"clicks":0,"open_rate":0,"click_rate":0,"created_at":"2026-10-22T08:52:08.762873Z","updated_at":"2026-10-22T08:52:08.762873Z"}],"meta":{"next_cursor":"ATFli9bJvH7vgqoL19WIaHd7P2ajK_3_gc-avJBnE93Vz7-BggnUFyd3INX0aogupEIO9GInVy69os7dJEXCtecC72rG","prev_cursor":null,"limit":1,"total":2}}Ugyanez a lista egy csoportra vagy szegmensre a GET /groups/{id}/subscribers és a GET /segments/{id}/subscribers címen is elérhető (filter[status], limit, cursor paraméterrel).
A következő oldalt a cursor paraméterben átadott next_cursor hozza. Az ott kapott prev_cursor visszavisz, szintén a cursor paraméterben (a feliratkozólista prev_cursor értéke b. előtaggal kezdődik; változtatás nélkül add vissza):
curl -g -H "Authorization: Bearer $ECHO_TOKEN" \ "$ECHO_API/subscribers?filter[group]=257e83a2-d55e-4a8c-b9a4-b3e939c151cc&limit=1&cursor=ATFli9bJvH7v..."{"data":[...],"meta":{"next_cursor":null,"prev_cursor":"b.ATFli9bJvH7vuyCx2u4V-jDq5wBEHY5rFldF82H_JvI92h0J4F4OC4I6KKepvM_8mmxMtw6iIl72qgodfvxCaS2-bJj7","limit":1,"total":2}}Egy nagyon nagy, lassú szűrés 503 list_timeout választ adhat: szűkítsd a szűrést, és próbáld újra.
Feliratkozók számlálása
Szekció neve “Feliratkozók számlálása”A GET /subscribers/count ugyanazt a filter[status] és filter[group] paramétert fogadja.
curl -g -H "Authorization: Bearer $ECHO_TOKEN" "$ECHO_API/subscribers/count?filter[status]=unsubscribed"{"data":{"total":193}}A total értéke null, ha a számolás túl sokáig tartott.
Feliratkozó felvétele vagy frissítése
Szekció neve “Feliratkozó felvétele vagy frissítése”A POST /subscribers felvesz egy feliratkozót, vagy frissíti azt, akinek már ez az e-mail-címe.
| Kulcs | Kötelező | Jelentés |
|---|---|---|
email |
igen | A cím. Az API levágja a szóközöket, és kisbetűsíti. |
fields |
nem | Értékek mezőkulcs szerint. A null törli az értéket, az üres szöveg nem változtat a tárolt értéken. |
groups |
nem | Csoportazonosítók, amelyekhez a feliratkozót hozzá kell adni. Csoportból ez sosem vesz ki. |
ip_address |
nem | A feliratkozás IP-címe, új feliratkozónál tárolódik. |
curl -X POST "$ECHO_API/subscribers" \ -H "Authorization: Bearer $ECHO_TOKEN" -H "Content-Type: application/json" \ -d '{"email":"[email protected]","fields":{"name":"Lilla","last_name":"Farkas","city":"Szeged","rendelesek_szama":3},"groups":["257e83a2-d55e-4a8c-b9a4-b3e939c151cc"],"ip_address":"203.0.113.25"}'Új feliratkozónál 201 Created:
{"data":{"id":"d5f0b4b1-b59d-40eb-b2e0-74857893a055","email":"[email protected]","status":"unconfirmed","source":"api","fields":{"city":"Szeged","last_name":"Farkas","name":"Lilla","rendelesek_szama":3},"groups":[{"id":"257e83a2-d55e-4a8c-b9a4-b3e939c151cc","name":"Webshop vásárlók"}],"signup_ip":"203.0.113.25","optin_ip":null,"subscribed_at":"2026-10-22T08:52:08.527488Z","opted_in_at":null,"unsubscribed_at":null,"timezone":null,"location_country":null,"location_city":null,"sent":0,"opens":0,"clicks":0,"open_rate":0,"click_rate":0,"created_at":"2026-10-22T08:52:08.527488Z","updated_at":"2026-10-22T08:52:08.527488Z"}}Ugyanazt a címet újra elküldve a feliratkozó frissül, a válasz 200 OK. Csak a megadott mezők változnak:
curl -X POST "$ECHO_API/subscribers" \ -H "Authorization: Bearer $ECHO_TOKEN" -H "Content-Type: application/json" \{"data":{"id":"d5f0b4b1-b59d-40eb-b2e0-74857893a055","email":"[email protected]","status":"unconfirmed","source":"api","fields":{"city":"Szeged","last_name":"Farkas","name":"Lilla","rendelesek_szama":3,"vasarloi_szint":"Ezüst"},"groups":[{"id":"257e83a2-d55e-4a8c-b9a4-b3e939c151cc","name":"Webshop vásárlók"}],"signup_ip":"203.0.113.25","optin_ip":null,"subscribed_at":"2026-10-22T08:52:08.527488Z","opted_in_at":null,"unsubscribed_at":null,"timezone":null,"location_country":null,"location_city":null,"sent":0,"opens":0,"clicks":0,"open_rate":0,"click_rate":0,"created_at":"2026-10-22T08:52:08.527488Z","updated_at":"2026-10-22T08:52:08.568881Z"}}Az új feliratkozó állapota. Ha a munkaterület feliratkozási beállításaiban az API-s feliratkozásokra be van kapcsolva a dupla megerősítés, az új feliratkozó unconfirmed állapotban indul, és megkapja a megerősítő levelet; megerősítés után active lesz. Ha ki van kapcsolva, rögtön active. A meglévő feliratkozó megtartja az állapotát: az API soha nem iratkoztat fel újra valakit, aki leiratkozott.
Az elutasított címek 422 validation választ adnak, az ok a fields.email kulcsban:
| Eset | fields.email (angol üzenet) |
|---|---|
| Nem érvényes cím | Enter a valid email address. |
| Szerepkör-cím, például abuse@ vagy postmaster@ | Role addresses such as abuse@ or postmaster@ can't be added. |
| Tiltólistán van (korábban visszapattant vagy spamnek jelölt) | This address is on the suppression list because it bounced or reported spam. |
{"error":{"code":"validation","message":"Please check the highlighted fields.","fields":{"email":"This address is on the suppression list because it bounced or reported spam."}}}A többi mezőhiba fields. előtaggal nevezi meg a kulcsot:
{"error":{"code":"validation","message":"Please check the highlighted fields.","fields":{"fields.rendelesek_szama":"Enter a number, e.g. 12 or 3.5."}}}{"error":{"code":"validation","message":"Please check the highlighted fields.","fields":{"fields.kedvenc_szin":"Unknown field."}}}Ismeretlen csoportazonosító: {"fields":{"groups":"Choose an existing group."}}. Ismeretlen felső szintű kulcs (például tags): {"fields":{"tags":"Unknown field."}}.
Egy feliratkozó lekérése
Szekció neve “Egy feliratkozó lekérése”A GET /subscribers/{id} a feliratkozó azonosítóját vagy e-mail-címét fogadja (ha a kliensed igényli, a @ jelet kódold %40 formára):
A válasz {"data": <feliratkozó>}, vagy 404 not_found:
{"error":{"code":"not_found","message":"Not found."}}E-mail-címet csak a GET fogad, a többi feliratkozó-végponthoz az azonosító kell.
Feliratkozó módosítása
Szekció neve “Feliratkozó módosítása”A PUT /subscribers/{id} egy tranzakcióban módosítja a mezőértékeket és hozzáadja a csoportokat. Minden kulcs elhagyható.
| Kulcs | Jelentés |
|---|---|
fields |
Értékek mezőkulcs szerint; a null törli az értéket. |
groups |
Hozzáadandó csoportazonosítók (kivenni nem vesz ki). |
status |
Csak unsubscribed (lent). |
curl -X PUT "$ECHO_API/subscribers/d5f0b4b1-b59d-40eb-b2e0-74857893a055" \ -H "Authorization: Bearer $ECHO_TOKEN" -H "Content-Type: application/json" \ -d '{"fields":{"city":"Pécs","company":null}}'{"data":{"id":"d5f0b4b1-b59d-40eb-b2e0-74857893a055","email":"[email protected]","status":"unconfirmed","source":"api","fields":{"city":"Pécs","last_name":"Farkas","name":"Lilla","rendelesek_szama":3,"vasarloi_szint":"Ezüst"},"groups":[{"id":"257e83a2-d55e-4a8c-b9a4-b3e939c151cc","name":"Webshop vásárlók"}],"signup_ip":"203.0.113.25","optin_ip":null,"subscribed_at":"2026-10-22T08:52:08.527488Z","opted_in_at":null,"unsubscribed_at":null,"timezone":null,"location_country":null,"location_city":null,"sent":0,"opens":0,"clicks":0,"open_rate":0,"click_rate":0,"created_at":"2026-10-22T08:52:08.527488Z","updated_at":"2026-10-22T08:52:10.212948Z"}}Az e-mail-cím az API-n át nem módosítható.
Feliratkozó leiratkoztatása
Szekció neve “Feliratkozó leiratkoztatása”curl -X PUT "$ECHO_API/subscribers/d5f0b4b1-b59d-40eb-b2e0-74857893a055" \ -H "Authorization: Bearer $ECHO_TOKEN" -H "Content-Type: application/json" \ -d '{"status":"unsubscribed"}'A válasz a feliratkozó "status":"unsubscribed" állapottal és kitöltött unsubscribed_at értékkel. Más állapotot az API elutasít, mert újra hozzájárulni csak a feliratkozó tud:
{"error":{"code":"validation","message":"Please check the highlighted fields.","fields":{"status":"Through the API a subscriber can only be unsubscribed."}}}Csoporthoz adás, eltávolítás csoportból
Szekció neve “Csoporthoz adás, eltávolítás csoportból”curl -X POST "$ECHO_API/subscribers/d5f0b4b1-b59d-40eb-b2e0-74857893a055/groups/257e83a2-d55e-4a8c-b9a4-b3e939c151cc" \ -H "Authorization: Bearer $ECHO_TOKEN"200 OK a feliratkozóval. Meglévő tag hozzáadása nem változtat semmin.
curl -X DELETE "$ECHO_API/subscribers/d5f0b4b1-b59d-40eb-b2e0-74857893a055/groups/257e83a2-d55e-4a8c-b9a4-b3e939c151cc" \ -H "Authorization: Bearer $ECHO_TOKEN"204 No Content. A csoporthoz adás elindíthat egy automatizálást, amelynek a csoportba lépés az indítója.
Feliratkozó törlése
Szekció neve “Feliratkozó törlése”curl -X DELETE "$ECHO_API/subscribers/8273ff7d-cb69-4a72-83e6-dbebbec33115" -H "Authorization: Bearer $ECHO_TOKEN"204 No Content. A feliratkozó törlődik; a korábbi eseményei a kampánystatisztikában maradnak, a személy nélkül. A törölt címről az Echo már nem tudja, hogy leiratkozott, így ha később újra felveszed, új feliratkozó lesz. Ha csak a leveleket állítanád le, de megtartanád az adatot, inkább iratkoztasd le.
Feliratkozó elfelejtése (GDPR)
Szekció neve “Feliratkozó elfelejtése (GDPR)”curl -X POST "$ECHO_API/subscribers/98cc16c4-cb25-4ec6-8dbe-9704c4e198c4/forget" -H "Authorization: Bearer $ECHO_TOKEN"204 No Content, és mire a válasz megérkezik, a törlés megtörtént: a feliratkozó, a jegyzetei, a csoporttagságai és az eseményeinek személyes adatai törlődnek. A cím később új feliratkozóként újra felvehető. Az elfelejtett feliratkozóról szóló subscriber.deleted webhookesemény csak az azonosítót viszi (Webhookok).
Egy feliratkozó tevékenysége
Szekció neve “Egy feliratkozó tevékenysége”A GET /subscribers/{id}/activity a feliratkozó eseményeit listázza, a legújabbal kezdve, oldalanként 50-et. Csak előre lapoz: a next_cursor értékét a cursor paraméterben add át; a prev_cursor mindig null.
filter |
Események |
|---|---|
all (alapértelmezett) |
Minden |
campaign_emails, automation_emails |
Elküldött kampány- vagy munkafolyamat-levelek |
opens, clicks |
Megnyitások, kattintások |
bounces, soft_bounces, junks |
Végleges és ideiglenes visszapattanások, spamjelentések |
unsubscribes, forwards |
Leiratkozások, továbbküldések |
marketing_preferences, preference_center |
Preferencia-változások |
curl -H "Authorization: Bearer $ECHO_TOKEN" \ "$ECHO_API/subscribers/1022eacd-0544-4c99-9b38-c678933ed6b9/activity?filter=clicks"{"data":[{"event_id":"87949","type":"click","source_kind":"campaign","occurred_at":"2026-10-01T08:25:03.153043Z","data":{"link":1,"ua":"Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/129.0.0.0 Safari/537.36"},"campaign":{"id":"522e9156-b62c-45df-8fa8-4d93715379fa","name":"VIP: őszi zártkörű vásár"},"automation":null},{"event_id":"87948","type":"click","source_kind":"campaign","occurred_at":"2026-10-01T08:24:03.153043Z","data":{"link":1,"ua":"Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/129.0.0.0 Safari/537.36"},"campaign":{"id":"522e9156-b62c-45df-8fa8-4d93715379fa","name":"VIP: őszi zártkörű vásár"},"automation":null},{"event_id":"51770","type":"click","source_kind":"campaign","occurred_at":"2026-08-06T07:38:17.436946Z","data":{"link":1,"ua":"Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/129.0.0.0 Safari/537.36"},"campaign":{"id":"d5ca5c93-93d3-49ad-8d0f-3a069952faee","name":"Őszi felmérés: mit ültetnél?"},"automation":null}],"meta":{"next_cursor":null,"prev_cursor":null,"limit":50}}A type értéke sent, delivered, open, click, bounce_hard, bounce_soft, complaint, unsubscribe, forward, preference_change, preference_center, optin_sent vagy preference_email. A source_kind értéke campaign, automation vagy null. A data tartalma a típustól függ (kattintásnál a link sorszáma a levélben és a böngésző azonosítója), és később új kulcsokkal bővülhet, ezért rugalmasan olvasd. A campaign és az automation megnevezi azt a kampányt vagy munkafolyamatot, amelynek a leveléhez az esemény tartozik (id és name), vagy null, ha nincs ilyen, vagy azóta törölték.
A hibás vagy lejárt kurzor 422 választ ad, fields.cursor hibával:
{"error":{"code":"validation","message":"Please check the highlighted fields.","fields":{"cursor":"Invalid value."}}}