Google Sheets-kapcsolatok importálása Brevóba Apps Scripttel

Egy tucat rendezvényes jelentkezőt könnyű egyszer exportálni. Második alkalommal egy cím duplán szerepelhet, egy másik személy pedig már leiratkozott a Brevóban. Az ismételhető importnak mindkettőt fel kell ismernie.

A szkript a Brevo kapcsolatolvasó, -létrehozó és -frissítő végpontjait használja. Kicsi, időzített importhoz való, nem tömeges betöltő vagy beépített Google Sheets-csatlakozó. Nem küld e-mailt. A hozzájárulás bizonyítékáért és az üzemeltetésért te felelsz.

Készítsd elő a táblát és a listát

Hozz létre Contacts lapot pontosan ezekkel a fejlécekkel. A consent oszlopban csak akkor legyen TRUE, ha az adott marketingcélra van hozzájárulás.

Hozz létre vagy válassz Brevo-listát, és a számszerű azonosítóját írd a LIST_ID mezőbe. A FNAME és LNAME attribútumoknak létezniük kell; a példa csak ezeket párosítja. A hozzájárulás idejét és módját bizonyító forrást külön őrizd meg, ha a tábla nem tartalmazza. A TRUE cella önmagában nem bizonyíték.

Az Extensions → Apps Script → Project Settings → Script Properties helyen add hozzá a BREVO_API_KEY értéket. A tulajdonságok a szkript felhasználói számára közösek, ezért korlátozd a szerkesztést. Ne tedd a kulcsot cellába vagy forráskódba. Lásd Google hozzáférési szabályait.

A szkript

Cseréld le a Code.gs tartalmát erre, és az első futás előtt állítsd be a LIST_ID értékét.

const LIST_ID = 42; // Replace with your existing Brevo list ID.
const TAB = 'Contacts';
const BASE = 'https://api.brevo.com/v3';

function syncSheetToBrevo() {
  const key = PropertiesService.getScriptProperties().getProperty('BREVO_API_KEY');
  if (!key) throw new Error('Set BREVO_API_KEY in Script Properties first');
  const sheet = SpreadsheetApp.getActiveSpreadsheet().getSheetByName(TAB);
  if (!sheet) throw new Error('Contacts tab missing');
  const values = sheet.getDataRange().getValues();
  const headers = values.shift().map(h => String(h).trim());
  const columns = ['email', 'firstName', 'lastName', 'consent']
    .map(name => headers.indexOf(name));
  if (columns.includes(-1)) throw new Error('Required header missing');
  const [emailCol, firstCol, lastCol, consentCol] = columns;
  const seen = new Set();
  const result = { written: 0, skipped: 0 };

  for (const row of values) {
    const email = String(row[emailCol] || '').trim().toLowerCase();
    if (row[consentCol] !== true || !/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email) || seen.has(email)) {
      result.skipped++;
      continue;
    }
    seen.add(email);
    const path = '/contacts/' + encodeURIComponent(email);
    const current = brevo_(key, path, 'get');
    if (current.code !== 200 && current.code !== 404) {
      throw new Error(`Contact read failed (${current.code}) for row ${result.written + result.skipped + 2}`);
    }
    if (current.code === 200) {
      const contact = JSON.parse(current.text);
      if (contact.emailBlacklisted || (contact.listUnsubscribed || []).includes(LIST_ID)) {
        result.skipped++;
        continue;
      }
    }
    const attributes = {};
    if (row[firstCol] !== '') attributes.FNAME = String(row[firstCol]);
    if (row[lastCol] !== '') attributes.LNAME = String(row[lastCol]);
    const body = { attributes, listIds: [LIST_ID] };
    const saved = current.code === 404
      ? brevo_(key, '/contacts', 'post', { email, ...body })
      : brevo_(key, path, 'put', body);
    if (![201, 204].includes(saved.code)) {
      throw new Error(`Contact write failed (${saved.code}) for ${email}: ${saved.text.slice(0, 200)}`);
    }
    result.written++;
  }
  Logger.log(JSON.stringify(result));
  return result;
}

function brevo_(key, path, method, body) {
  for (let attempt = 0; attempt < 3; attempt++) {
    const response = UrlFetchApp.fetch(BASE + path, {
      method,
      contentType: 'application/json',
      headers: { 'api-key': key },
      payload: body ? JSON.stringify(body) : undefined,
      muteHttpExceptions: true,
    });
    const code = response.getResponseCode();
    if (code !== 429) return { code, text: response.getContentText() };
    if (attempt === 2) return { code, text: response.getContentText() };
    const reset = Object.entries(response.getHeaders()).find(
      ([name]) => name.toLowerCase() === 'x-sib-ratelimit-reset'
    );
    const raw = Number(reset && reset[1]);
    const seconds = Number.isFinite(raw) && raw > 0 ? raw : 2 ** attempt;
    const waitSeconds = seconds + 2 ** attempt;
    if (waitSeconds > 60) return { code, text: response.getContentText() };
    Utilities.sleep(waitSeconds * 1000);
  }
}

Mentsd el, válaszd a syncSheetToBrevo függvényt, majd kattints a Run gombra. Google engedélyt kér a táblához és külső kérésekhez. Az Executions nézetben keresd a {written, skipped} naplót. A 404-es olvasás létrehozáshoz, a 200-as frissítéshez vezet; más hiba megállítja a futást. A sikeres kapcsolatírás nem jelent kampányküldést.

A szkript egy futáson belül kiszűri az ismétlődő címeket, a következő futásban pedig újra lekérdezi a Brevót. Nem állítja az emailBlacklisted értékét false-ra és nem módosít címet. Globális tiltás vagy a cél-listáról való leiratkozás esetén a sort TRUE mellett is kihagyja. Ne használd leiratkozás visszavonására. A Brevo szerint a blokkolt kapcsolat címének cseréje feloldhatja a blokkolást.

Egy futás ellenőrzése időzítés előtt

Használj saját tesztlistát és tesztkapcsolatokat. Egy TRUE, egy FALSE és egy duplikált címmel egy írás és két kihagyás várható. Iratkoztasd le a tesztkapcsolatot, majd futtasd újra: hozzá nem tartozhat új írás. Hibateszthez ideiglenesen adj meg érvénytelen LIST_ID értéket, ellenőrizd a HTTP-hibát az Executions nézetben, állítsd vissza és ismételd meg. Ne tesztelj valódi ügyfélrekordokon. A cikk kódját helyben, mock Brevo-válaszokkal ellenőriztük, élő írás nélkül.

Az Apps Script → Triggers → Add Trigger menüben időzítsd a syncSheetToBrevo függvényt. A triggerek a létrehozó fiókjában futnak, amelynek meg kell tartania a táblához való hozzáférést. Kis táblánál indulj napi futással és nézd a hibákat. Google korlátozza a futási időt és az URL Fetch használatát; nagy forrásokat bonts korlátozott feladatokra.

A 429 után a szkript a x-sib-ratelimit-reset alapján legfeljebb kétszer próbálkozik. Ha a szükséges várakozás 60 másodpercnél hosszabb, 429-cel megáll egy későbbi futásig. Más hibánál is megáll, majd a következő futás elölről kezd. A kapcsolat az olvasás és írás között leiratkozhat; a példa csak akkor megfelelő, ha ez a szűk versenyablak elfogadható. Szigorúbb védelemhez eseményegyeztetés, megbízható hozzájárulási tár és küldés előtti utolsó ellenőrzés kell.

Nagy táblákhoz a Brevo aszinkron importja processId értéket ad. Ez a feladat elfogadása, nem a befejezése. Az eredményt külön ellenőrizd. A kapcsolatonkénti példa a hibát a megfelelő sornál mutatja meg.