# Csoportok, szegmensek és mezők

> Olvasáshoz Feliratkozók: megtekintés, íráshoz Feliratkozók: kezelés jog kell.

Olvasáshoz Feliratkozók: megtekintés, íráshoz Feliratkozók: kezelés jog kell.

## Csoportok

| Metódus és útvonal | Mit csinál |
|---|---|
| `GET /groups` | Csoportok név szerint. `filter[name]` (a név tartalmazza), `limit`, `cursor`. |
| `POST /groups` | Csoportot hoz létre: `{"name": "..."}`. `201`. |
| `PUT /groups/{id}` | Átnevez: `{"name": "..."}`. `200`. |
| `DELETE /groups/{id}` | Töröl (a feliratkozók megmaradnak). `204`. |
| `GET /groups/{id}/subscribers` | A csoport feliratkozói ([Feliratkozók listázása](https://docs.uptools.io/hu/echo/developer-guide/subscribers/#feliratkozók-listázása)). |
| `POST /groups/{id}/import-subscribers` | Tömeges import a csoportba ([Importálás API-val](https://docs.uptools.io/hu/echo/developer-guide/import/)). |

**Csoport létrehozása**

```bash
curl -X POST "$ECHO_API/groups" \
  -H "Authorization: Bearer $ECHO_TOKEN" -H "Content-Type: application/json" \
  -d '{"name":"Webshop vásárlók"}'
```

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

**Keresés név szerint**

```bash
curl -g -H "Authorization: Bearer $ECHO_TOKEN" "$ECHO_API/groups?filter[name]=VIP"
```

```json
{"data":[{"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}],"meta":{"next_cursor":null,"prev_cursor":null,"limit":25,"total":1}}
```

| Kulcs | Jelentés |
|---|---|
| `subscribers` | Aktív tagok. |
| `total` | Tagok bármilyen állapotban. |
| `open_rate`, `click_rate` | A tagok átlagos aránya, százalékban. |
| `timed_out` | Csak listában: `true`, ha a számolás feladta, ilyenkor a számok `null` értékűek. |

**Átnevezés és törlés**

```bash
curl -X PUT "$ECHO_API/groups/257e83a2-d55e-4a8c-b9a4-b3e939c151cc" \
  -H "Authorization: Bearer $ECHO_TOKEN" -H "Content-Type: application/json" \
  -d '{"name":"Webshop vásárlók 2026"}'
curl -X DELETE "$ECHO_API/groups/257e83a2-d55e-4a8c-b9a4-b3e939c151cc" -H "Authorization: Bearer $ECHO_TOKEN"
```

Foglalt név esetén a válasz `409 name_taken`. Azt a csoportot, amelyet szegmens, kampány vagy munkafolyamat használ, nem lehet törölni:

```json
{"error":{"code":"in_use","message":"It's used by these segments: Visszatérő webshop vásárlók"}}
```

A csoport törlése nem küld `subscriber.removed_from_group` webhookeseményt a tagjairól.

## Szegmensek

A szegmensek mentett szűrők. A feltételeiket a felületen szerkeszted; az API olvassa, átnevezi és törli őket.

| Metódus és útvonal | Mit csinál |
|---|---|
| `GET /segments` | Szegmensek név szerint. `filter[name]`, `limit`, `cursor`. |
| `GET /segments/{id}/subscribers` | A most megfelelő feliratkozók. |
| `PUT /segments/{id}` | Átnevez: `{"name": "..."}`. Bármilyen más kulcs `422`. |
| `DELETE /segments/{id}` | Töröl. `409 in_use`, ha kampány vagy munkafolyamat használja. |

```bash
curl -H "Authorization: Bearer $ECHO_TOKEN" "$ECHO_API/segments?limit=1"
```

```json
{"data":[{"id":"026c692e-e106-4bb6-b971-78757cb3fd02","name":"Aktív olvasók (30 nap)","rules":{"version":1,"groups":[[{"type":"email_actions","op":"opened_or_clicked","amount":30}]]},"subscribers":2428,"open_rate":52.88,"click_rate":11.32,"counted_at":"2026-10-22T05:16:28.536739Z","created_at":"2026-05-12T08:00:00Z","updated_at":"2026-05-15T08:00:00Z","timed_out":false}],"meta":{"next_cursor":"bzox","prev_cursor":null,"limit":1,"total":6}}
```

A `subscribers`, az `open_rate` és a `click_rate` az utolsó számolásból (`counted_at`) jön; a `timed_out` értéke `true`, ha az utolsó számolás feladta, és a számok régebbiek. A `rules` a szegmens feltételrendszere úgy, ahogy a felület tárolja: csak olvasd.

```bash
curl -X PUT "$ECHO_API/segments/6010f9ca-331d-4c81-a3ab-1ed48a62a12b" \
  -H "Authorization: Bearer $ECHO_TOKEN" -H "Content-Type: application/json" \
  -d '{"name":"Visszatérő webshop vásárlók"}'
```

```json
{"data":{"id":"6010f9ca-331d-4c81-a3ab-1ed48a62a12b","name":"Visszatérő webshop vásárlók","rules":{"version":1,"groups":[[{"type":"groups","op":"belongs_to","values":["257e83a2-d55e-4a8c-b9a4-b3e939c151cc"]}]]},"subscribers":2,"open_rate":0,"click_rate":0,"counted_at":"2026-10-22T08:52:10.230434Z","created_at":"2026-10-22T08:52:10.217956Z","updated_at":"2026-10-22T08:52:10.234278Z","timed_out":false}}
```

## Mezők

A mezők a feliratkozók adatait tárolják. A beépített mezők (`email`, `name`, `last_name`, `company`, `country`, `city`, `phone`, `state`, `zip`) mindig megvannak, a saját mezőket munkaterületenként veszed fel. A feliratkozók törzsében a mező `key` értékét használod.

| Metódus és útvonal | Mit csinál |
|---|---|
| `GET /fields` | Előbb a beépített, aztán a saját mezők. Nincs lapozás. |
| `POST /fields` | Saját mezőt hoz létre: `{"name": "...", "type": "text" \| "number" \| "date"}`. `201`. |
| `PUT /fields/{key}` | Átnevez: `{"name": "..."}`. A kulcs és a címke marad. |
| `DELETE /fields/{key}` | Törli a saját mezőt és az értékét minden feliratkozónál. `204`. |

```bash
curl -H "Authorization: Bearer $ECHO_TOKEN" "$ECHO_API/fields"
```

```json
{"data":[{"key":"email","name":"Email","type":"text","builtin":true,"tag":"{$email}","created_at":null},{"key":"name","name":"Name","type":"text","builtin":true,"tag":"{$name}","created_at":null},{"key":"last_name","name":"Last name","type":"text","builtin":true,"tag":"{$last_name}","created_at":null},{"key":"company","name":"Company","type":"text","builtin":true,"tag":"{$company}","created_at":null},{"key":"country","name":"Country","type":"text","builtin":true,"tag":"{$country}","created_at":null},{"key":"city","name":"City","type":"text","builtin":true,"tag":"{$city}","created_at":null},{"key":"phone","name":"Phone","type":"text","builtin":true,"tag":"{$phone}","created_at":null},{"key":"state","name":"State","type":"text","builtin":true,"tag":"{$state}","created_at":null},{"key":"zip","name":"Zip","type":"text","builtin":true,"tag":"{$zip}","created_at":null},{"key":"szuletesnap","name":"Születésnap","type":"date","builtin":false,"tag":"{$szuletesnap}","created_at":"2026-04-16T06:55:00Z"},{"key":"rendelesek_szama","name":"Rendelések száma","type":"number","builtin":false,"tag":"{$rendelesek_szama}","created_at":"2026-04-16T06:55:00Z"}]}
```

(A válasz rövidítve: a demó munkaterületnek van még néhány saját mezője.)

**Saját mező létrehozása, átnevezése, törlése**

```bash
curl -X POST "$ECHO_API/fields" \
  -H "Authorization: Bearer $ECHO_TOKEN" -H "Content-Type: application/json" \
  -d '{"name":"Kedvenc növény","type":"text"}'
```

```json
{"data":{"key":"kedvenc_noveny","name":"Kedvenc növény","type":"text","builtin":false,"tag":"{$kedvenc_noveny}","created_at":"2026-10-22T08:52:10.268043Z"}}
```

A kulcs a névből készül (kisbetűk, ékezetek nélkül, a szóközök helyett `_`). Ne magad állítsd elő, hanem olvasd ki a válaszból.

```bash
curl -X PUT "$ECHO_API/fields/kedvenc_noveny" \
  -H "Authorization: Bearer $ECHO_TOKEN" -H "Content-Type: application/json" \
  -d '{"name":"Kedvenc virág"}'
curl -X DELETE "$ECHO_API/fields/kedvenc_noveny" -H "Authorization: Bearer $ECHO_TOKEN"
```

| Hiba | Mikor |
|---|---|
| `409 name_taken` | Már van ilyen nevű mező. |
| `409 builtin_field` | Beépített mezőt próbáltál átnevezni vagy törölni. |

```json
{"error":{"code":"builtin_field","message":"Default fields can't be renamed or deleted."}}
```

## Időzónák

A `GET /timezones` az Echo által elfogadott IANA időzónaneveket listázza (például a [kampány időzítéséhez](https://docs.uptools.io/hu/echo/developer-guide/campaigns/#időzítés-és-visszavonás)). Bármely érvényes token hívhatja.

```json
{"data":[{"id":"Africa/Abidjan"},{"id":"Africa/Accra"},{"id":"Africa/Addis_Ababa"}]}
```

(Rövidítve.)