Feliratkozók importálása CSV-ből vagy API-n keresztül

Háromféleképpen adhatsz hozzá feliratkozókat

A Yaplet támogatja a tömeges CSV-feltöltést, a REST API-t és az egyenkénti manuális bevitelt. A három útvonal eltérően kezeli azt a címet, amely már szerepel a listádon: a CSV-import kihagyja, és pontosan úgy hagyja, ahogy volt, a kézi űrlap elutasítja („A feliratkozó már létezik”), és csak a bulk-upsert API frissíti. Egyik sem hoz létre soha másolatot.

1. lehetőség — CSV-fájl feltöltése

Menj a Marketing → Hírlevél → Feliratkozók oldalra, és kattints a Feliratkozó hozzáadása gombra. Ez megnyitja az importálási oldalt, ahol alapértelmezetten az Importálás CSV/TXT-ből fül van kiválasztva. Letölthető sablonfájl nincs — az oldal két beépített CSV-példát mutat (Sablon példa 1 és Sablon példa 2), amelyeket átmásolhatsz és szerkeszthetsz.

1. Készítsd elő a fájlt legalább egy email oszloppal. Az email oszlopfejlécet a rendszer automatikusan felismeri (kis- és nagybetű érzéketlenül). A névoszlopot is automatikusan felismeri olyan fejlécekből, amelyek tartalmazzák a name, firstname vagy lastname szót — ha a firstname és a lastname is jelen van, a rendszer egyetlen névvé fűzi össze őket.
2. Adj hozzá bármilyen egyéni mezőhöz tartozó oszlopot is. Csak az egyéni mezők oszlopainak kell pontosan egyezniük a taggel — az ismeretlen oszlopokat a rendszer figyelmen kívül hagyja.
3. Töltsd fel a fájlt. Az importálás gombon megjelenik a beolvasott sorok száma — ez az egyetlen visszajelzés a beküldés előtt.
4. Kapcsold be az Ellenőrző email küldése opciót, ha azt szeretnéd, hogy minden importált névjegy erősítse meg a feliratkozását, mielőtt kampányokat kap. Kapcsold ki, ha azonnal Hitelesített állapotba szeretnéd importálni őket (egy háttérben futó e-mail-formátum ellenőrzés után).
5. Kattints a Feliratkozók importálása gombra. Az importálás két perc után időtúllépéssel leáll — bontsd több fájlra, ha néhány ezer sornál nagyobb az állomány.

Minden olyan sor, amelynek e-mail-címe már szerepel a listán, kihagyásra kerül, nem frissül: a névjegy megtartja a jelenlegi nevét, egyéni mezőértékeit, csoporttagságait és állapotát, az importálás pedig duplikátumként jelenti. Egy CSV újratöltése tehát nem alkalmas a már meglévő névjegyek tömeges szerkesztésére, és nem is adja hozzá őket a feltöltési képernyőn kiválasztott csoportokhoz — erre a bulk-upsert API való.

A Yaplet importálás közben ingyen szűri a címeket. Minden olyan sor, amely érvénytelen formátumú, eldobható vagy átmeneti tartományhoz tartozik, vagy rendszer-/szerepcím (mint a no-reply@, postmaster@ vagy abuse@), kihagyásra kerül a beszúrás előtt. Kapsz egy Lista megtisztítva összegzést, okonkénti bontással — például „42 kézbesíthetetlen cím kihagyva: 30 érvénytelen, 5 eldobható, 7 rendszer/no-reply.” A duplikátumokról külön értesítés szól, amely megmondja, hány sor szerepelt már a listádon. Ugyanez a szűrő fut a bulk-upsert API-n is, amely a kihagyott darabszámokat a válaszában adja vissza.

A Yaplet emellett nyilvántartja azokat a címeket, amelyek a platformon bárhol véglegesen visszapattantak — vagyis a postafiók már nem létezik. Ha a fájlod ilyet tartalmaz, a feliratkozó bekerül a listádra, de azonnal Visszapattant állapotban, és soha nem kap levelet: a levelezőszolgáltató úgyis visszautasítaná az üzenetet, a kísérlet pedig csak a küldési reputációdba kerülne. Ez fordítva is működik — ha egy cím a Yapleten bárhol véglegesen visszapattan, minden listán Visszapattant állapotba kerül, amelyen szerepel, így egy feliratkozó akkor is Visszapattant lehet, ha te sosem küldtél neki. Csak a végleges visszapattanás működik így. A leiratkozás és a spam-panasz egy adott feladóról szóló döntés, ezért soha nem kerül át más fiókok közé — sem te nem tudsz meg semmit más Yaplet-fiókokról, sem ők a tiédről.

Amit a Yaplet nem tud ellenőrizni, az az, hogy egy jó formátumú cím mögött valóban létezik-e postafiók. Meg nem erősített, vásárolt vagy elavult lista importálása visszapattanásokat és spam-panaszokat okoz — a magas arány pedig automatikusan leállítja a küldésedet (lásd: Figyeld az e-mail-kézbesíthetőségedet). Ha egy lista nagy része használhatatlannak bizonyul, a Yaplet jelzi, és javasolja, hogy előbb ellenőrizd egy olyan szolgáltatással, mint a ZeroBounce, a Kickbox vagy a MillionVerifier. Csak olyan listákat importálj, amelyek a tiéd, és van engedélyed őket emailezni.

Ugyanez a háttérellenőrzés megnézi minden újonnan hozzáadott cím tartományát is: ha a tartománynak egyáltalán nincs levelezőszervere, a névjegy Eltávolítva állapotba kerül, mielőtt visszapattanhatna. Fájlimport után importonként egy értesítést kapsz a vezérlőpultban arról, hogy a kézbesíthetetlen címeket eltávolítottuk; az API-n vagy munkafolyamaton keresztül hozzáadott címeket értesítés nélkül távolítjuk el. A listádon már szereplő feliratkozókat nem ellenőrizzük újra.

2. lehetőség — Tömeges upsert API-n keresztül

Küldj hitelesített POST kérést a bulk-upsert végpontra. A hitelesítés a szervezeted API-kulcsával történik a Y-API-Key fejlécben. Egyetlen kérésben legfeljebb 20 000 névjegyet küldj — a nagyobb mennyiséget bontsd több hívásra.

POST https://yaplet.com/api/newsletter/contacts/bulk-upsert
Y-API-Key: your-api-key
Content-Type: application/json

{
  "contacts": [
    {
      "email": "[email protected]",
      "name": "Jane Smith",
      "state": "VERIFIED",
      "fields": { "plan": "pro", "country": "HU" },
      "group_add": ["group-uuid-here"],
      "group_remove": ["other-group-uuid"]
    }
  ]
}

Az egyes névjegyobjektumok mezői:

Mező	Típus	Kötelező	Megjegyzések
email	string	Igen	Az egyedi kulcs a szervezeted azonosítójával együtt. A meglévő névjegyek frissülnek.
name	string	Nem	Csak új névjegyek esetén esik vissza az e-mail-cím @ jel előtti részére, ha üres. A meglévő névjegyek megtartják a jelenlegi nevüket, ha nem küldesz nevet.
state	string	Nem	Elfogadott értékek: VERIFIED, UNVERIFIED, REMOVED. Bármely más értéket a rendszer csendben eldob. A VERIFIED soha nem érvényesül közvetlenül: új névjegynél vagy REMOVED állapotúnál NEW-ként mentjük, és a szokásos háttérben futó címellenőrzésen megy át, mielőtt Hitelesített lesz. Minden más meglévő névjegynél a VERIFIED nem érvényesül. A visszapattant vagy panaszt tett névjegyek megtartják az állapotukat, bármit küldesz; a leiratkozottakról lásd lent.
verification_id	UUID	Nem	A küldendő visszaigazoló e-mail-változat. A munkaterületed saját ellenőrző e-mail-változatainak egyike kell legyen — különben az egész kérés 400 Unknown verification_id hibával meghiúsul. Az új névjegyek először NEW állapotba kerülnek; a háttérellenőrzés ezután Nem hitelesített (az e-mail elküldésével) vagy Hitelesített állapotba lépteti őket a visszaigazolási kapcsoló és az e-mail-formátum érvényessége alapján.
fields	object	Nem	Kulcs-érték objektum, az egyéni mezőtagokkal kulcsolva. A típusok a mező definíciójához vannak ellenőrizve.
group_add	UUID[]	Nem	Csoportazonosítók tömbje, amelyekhez a névjegyet hozzá kell adni.
group_remove	UUID[]	Nem	Csoportazonosítók tömbje, amelyekből a névjegyet el kell távolítani.
created_at	ISO string	Nem	A névjegy létrehozási időbélyegének felülírása (hasznos másik platformról való átköltözéskor).

A sikeres válasz { "success": true, "results": [...] } formátumú, és tartalmazza a beillesztett vagy frissített névjegyeket. Hibák:

• 401 — hiányzó vagy érvénytelen Y-API-Key.
• 400 — a csomagod névjegy-limitje túllépve.
• 400 — a contacts hiányzik, üres, vagy nem tömb.
• 400 — 20 000-nél több névjegy egyetlen kérésben.
• 400 — Unknown verification_id: egy verification_id nem a munkaterületed saját ellenőrző e-mail-változatainak egyike. Ilyenkor semmi nem mentődik el.

Az érvénytelen state értékek és az ismeretlen egyéni mezőtagek nem váltanak ki hibát — a rendszer csendben kiszűri őket az upsert előtt. Az eldobások észleléséhez hasonlítsd össze a válasz results.length értékét az elküldött contacts tömb méretével.

A meglévő névjegyeket az (email, org_id) páros alapján azonosítja: a név, a mezők és a csoporttagságok frissülnek; a meglévő állapot megmarad, kivéve, ha kifejezetten új állapotértéket küldesz.

A „nem” az „nem” marad. A visszapattant vagy panaszt tett névjegyek megtartják az állapotukat, bármit küldesz — a nevük, a mezőik és a csoportjaik viszont frissülnek. A leiratkozott névjegy szintén kimarad a kampányaidból. Ha verification_id-val küldöd, a Yaplet új ellenőrző e-mailt küld az illetőnek — címenként legfeljebb 30 naponta egyet; a 30 napon belüli újabb kérés semmit nem változtat. Az e-mail után a névjegy Nem hitelesített állapotban vár, nem kap kampányokat, és csak akkor lesz Hitelesített, ha az illető megerősíti. verification_id nélkül Leiratkozott marad. Ugyanez érvényes egy korábban törölt címre is, amelyet most újra elküldesz. A válaszban minden névjegy azzal az állapottal szerepel, amelybe ténylegesen került.

3. lehetőség — Feliratkozó manuális hozzáadása

Egyetlen névjegy esetén kattints a Feliratkozó hozzáadása gombra a Feliratkozók oldalon — ez megnyitja az importálási oldalt —, majd válts át az Egyetlen feliratkozó hozzáadása fülre. Add meg az e-mail-címet és a nevet — mindkettő kötelező —, az egyéni mezők értékeit, és a csoportokat, amelyekhez hozzá szeretnéd adni. Kattints a Feliratkozó hozzáadása gombra.

Feliratkozói állapotok importálás után

Minden importált sor először Új állapotba kerül. Egy háttérfeladat ezután ellenőrzi az e-mail formátumát, és a választott Ellenőrző email küldése beállítás alapján lépteti tovább a névjegyet:

Állapot	Jelentése
Új	Átmeneti állapot közvetlenül az importálás után. A háttérellenőrzés másodperceken belül felveszi a sort, és az alábbi állapotok valamelyikébe lépteti. Egy kivétel — ha ingyenes csomagon vagy, és bekapcsolt Ellenőrző email küldése mellett importáltál, minden megerősítő e-mail egy kreditbe kerül; üres kreditegyenleggel a névjegyek Új állapotban maradnak, amíg fel nem töltöd, utána maguktól továbblépnek.
Hitelesített	Kampányokat kap. Akkor állítódik be, ha az importáláskor a visszaigazolás ki volt kapcsolva és az e-mail formátuma érvényes, vagy ha a feliratkozó rákattint a megerősítő linkre.
Nem hitelesített	Az importáláskor a visszaigazolás be volt kapcsolva és az e-mail formátuma érvényes. A rendszer megerősítő e-mailt küld; a névjegy addig nem kap kampányokat, amíg rá nem kattint a linkre.
Leiratkozott	Leiratkozott. Az újraimportálás nem aktiválja újra.
Visszapattant	Visszapattanó (hard bounce) rögzítve az e-mail-szolgáltató részéről — vagy egy olyan cím, amelyről tudjuk, hogy véglegesen kézbesíthetetlen, akkor is, ha te sosem küldtél rá. Az újraimportálás nem aktiválja újra.
Panaszkodott	A címzett spamnek jelölte az üzenetet (SES vagy Hyvor webhook jelzi). Az újraimportálás nem aktiválja újra.
Eltávolítva	Manuálisan el lett távolítva a listáról, vagy a háttérellenőrzés érvénytelennek minősítette az e-mail formátumát, vagy a cím tartományának nincs levelezőszervere.

A Leiratkozott, a Visszapattant és a Panaszkodott olyan „nem”, amelyet a munkaterületed nem tud visszacsinálni: sem CSV-import, sem API-hívás, sem a feliratkozó szerkesztése, sem a Feliratkozók ellenőrzése művelet, sem a munkaterületedhez kapcsolt AI asszisztens nem tudja visszakapcsolni a névjegyet. A névjegy törlése és újbóli hozzáadása sem segít — a Yaplet munkaterületenként megjegyzi, mely címek mondtak nemet, és az újra hozzáadott névjegy a régi állapotával tér vissza. Leiratkozás után csak maga a személy térhet vissza, ha saját maga megerősíti a feliratkozását; visszapattanás vagy panasz után még így sem. Lásd: Leiratkozások és dupla opt-in.

Miután a feliratkozók bekerültek a listádba, mindegyikük rendelkezik egy Aktivitás értékkel, amely a Feliratkozók tábla egyik oszlopaként jelenik meg (a feliratkozó-szerkesztőben Aktivitási pontszám néven szerepel) — automatikusan frissül, ahogy a feliratkozó olvassa a leveleidet (egy valódi megnyitás 10 pontot ér, egy linkkattintás 50-et, minden kiküldött e-mail pedig előbb 10%-kal csökkenti, így a pontszám fokozatosan lecsökken, ha valaki már nem olvassa a leveleidet), és a magasabb pontszámú feliratkozók kerülnek előbb sorba minden kampányban.

Mi a következő lépés?

Most, hogy megvannak a feliratkozóid, rendezd őket dinamikus szegmensekbe vagy statikus csoportokba, hogy a kampányokban meghatározott közönséget célozz meg.