# Feliratkozók

> Listázás, számlálás, felvétel vagy frissítés, olvasás, módosítás, leiratkoztatás, törlés, elfelejtés, tevékenység.

Olvasáshoz Feliratkozók: megtekintés, íráshoz Feliratkozók: kezelés jog kell ([Hitelesítés](https://docs.uptools.io/hu/echo/developer-guide/authentication/)).

## A feliratkozó objektum

```json
{
  "id": "d5f0b4b1-b59d-40eb-b2e0-74857893a055",
  "email": "lilla.farkas@example.com",
  "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](https://docs.uptools.io/hu/echo/developer-guide/groups-segments-fields/#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

`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](https://docs.uptools.io/hu/echo/developer-guide/quickstart/#lapozás)). |

```bash
curl -g -H "Authorization: Bearer $ECHO_TOKEN" \
  "$ECHO_API/subscribers?filter[group]=257e83a2-d55e-4a8c-b9a4-b3e939c151cc&limit=1"
```

```json
{"data":[{"id":"98cc16c4-cb25-4ec6-8dbe-9704c4e198c4","email":"reka.toth@example.org","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):

```bash
curl -g -H "Authorization: Bearer $ECHO_TOKEN" \
  "$ECHO_API/subscribers?filter[group]=257e83a2-d55e-4a8c-b9a4-b3e939c151cc&limit=1&cursor=ATFli9bJvH7v..."
```

```json
{"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

A `GET /subscribers/count` ugyanazt a `filter[status]` és `filter[group]` paramétert fogadja.

```bash
curl -g -H "Authorization: Bearer $ECHO_TOKEN" "$ECHO_API/subscribers/count?filter[status]=unsubscribed"
```

```json
{"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

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. |

```bash
curl -X POST "$ECHO_API/subscribers" \
  -H "Authorization: Bearer $ECHO_TOKEN" -H "Content-Type: application/json" \
  -d '{"email":"lilla.farkas@example.com","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`:

```json
{"data":{"id":"d5f0b4b1-b59d-40eb-b2e0-74857893a055","email":"lilla.farkas@example.com","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:

```bash
curl -X POST "$ECHO_API/subscribers" \
  -H "Authorization: Bearer $ECHO_TOKEN" -H "Content-Type: application/json" \
  -d '{"email":"lilla.farkas@example.com","fields":{"vasarloi_szint":"Ezüst"}}'
```

```json
{"data":{"id":"d5f0b4b1-b59d-40eb-b2e0-74857893a055","email":"lilla.farkas@example.com","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.` |

```json
{"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:

```json
{"error":{"code":"validation","message":"Please check the highlighted fields.","fields":{"fields.rendelesek_szama":"Enter a number, e.g. 12 or 3.5."}}}
```

```json
{"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

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):

```bash
curl -H "Authorization: Bearer $ECHO_TOKEN" "$ECHO_API/subscribers/lilla.farkas@example.com"
```

A válasz `{"data": <feliratkozó>}`, vagy `404 not_found`:

```json
{"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

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](#feliratkozó-leiratkoztatása)). |

```bash
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}}'
```

```json
{"data":{"id":"d5f0b4b1-b59d-40eb-b2e0-74857893a055","email":"lilla.farkas@example.com","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

```bash
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:

```json
{"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

```bash
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.

```bash
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

```bash
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)

```bash
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](https://docs.uptools.io/hu/echo/developer-guide/webhooks/)).

## 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 |

```bash
curl -H "Authorization: Bearer $ECHO_TOKEN" \
  "$ECHO_API/subscribers/1022eacd-0544-4c99-9b38-c678933ed6b9/activity?filter=clicks"
```

```json
{"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:

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