Transmetime

draft = {  audienceIds: ["aud_4c1b8e2a7d9f05c36b4e8a71"],  from: "Acme <[email protected]>",  subject: "{{firstName|Hello}}, the September release is out",  html: "<p>Hi {{firstName|there}},</p><p>Here is what changed this month.</p>",  text: "Hi {{firstName|there}}, here is what changed this month. Unsubscribe: {{unsubscribeUrl}}",  tags: {campaign: "release-2026-09"}} reach = client.broadcasts.preview(draft)puts reach[:recipients], reach[:unsubscribed], reach[:suppressed] broadcast = client.broadcasts.send(draft) latest = client.broadcasts.get(broadcast[:id])while %w[scheduled queued sending].include?(latest[:status])  sleep 5  latest = client.broadcasts.get(broadcast[:id])end client.broadcasts.iterate_recipients(broadcast[:id]) do |copy|  puts copy[:email], copy[:status], copy[:opens], copy[:clicks]end bounced = client.broadcasts.list_recipients(broadcast[:id], filter: "bounced")bounced.items.each { |row| puts "#{row[:emailId]} #{row[:email]}" } copy = client.broadcasts.get_recipient(broadcast[:id], "msg_01dad25067bc4dac966d515d")puts copy[:subject], copy[:bouncedAt] stats = client.broadcasts.stats(broadcast[:id], grain: "day")puts stats.dig(:totals, :opened), stats.dig(:totals, :clicked), stats.dig(:totals, :unsubscribed) lately = client.broadcasts.stats(broadcast[:id], days: 1)puts lately.dig(:window, :opened) later = client.broadcasts.send(draft, scheduledAt: "P1D")client.broadcasts.cancel(later[:id]) history = client.broadcasts.list(audience_id: draft[:audienceIds].first)puts latest[:status], latest.dig(:counts, :sent), history.items.size month = client.broadcasts.analytics(days: 30)month[:broadcasts].each do |row|  puts row[:subject], row[:sent], row[:opened]end

Një transmetim dërgon një mesazh te të gjithë në një ose më shumë audienca, si kopje më vete për çdo person. Çdo kopje ka saktësisht një marrës dhe as cc, as bcc, ndaj askush nuk sheh se kujt tjetër i shkoi, dhe çdo kopje është një email i zakonshëm me id-në e vet msg_, ngjarje, gjurmim dhe webhook-e. list_recipients i liston me atë që ndodhi me secilën. Kopjet nuk ruhen në dosjen Të dërguarat, sepse regjistri është vetë transmetimi.

send kthehet menjëherë me transmetimin queued, ose scheduled kur jepni scheduledAt:, dhe dërgimi kryhet në sfond. send kërkon emails:send dhe audiences:read, dhe preview kërkon audiences:read. list, list_all, iterate, get, list_recipients, list_all_recipients, iterate_recipients, get_recipient, stats dhe analytics kërkojnë emails:read, dhe cancel kërkon emails:send.

broadcast = client.broadcasts.send(  audienceIds: ["aud_4c1b8e2a7d9f05c36b4e8a71"],  from: "Acme <[email protected]>",  subject: "Doors open on Friday",  text: "Hi {{firstName|there}}, doors open at nine. Unsubscribe: {{unsubscribeUrl}}",  scheduledAt: Time.now + 3600,  idempotency_key: "doors-open-2026-10") puts broadcast[:id], broadcast[:status], broadcast[:replayed]

Fushat e një transmetimi janë argumente me fjalë kyçe ose një Hash i vetëm, dhe ruajnë emrat camelCase të API-së (audienceIds:, scheduledAt:). idempotency_key: dhe api_key: janë opsione të thirrjes dhe nuk dërgohen kurrë si fusha. Fjalët kyçe të dhëna pranë një Hash-i bashkohen me të, ndaj send(draft, scheduledAt: "P1D") e dërgon të njëjtin draft një ditë më vonë. scheduledAt: merr një Time, një DateTime, një string ISO 8601 ose një kohëzgjatje si PT2H, dhe një Time dërgohet si çast UTC. preview dërgon vetëm audienceIds nga ajo që i jepni, ndaj merr të njëjtin Hash si send. Një përgjigje është një Hash me çelësa Symbol, ndaj broadcast[:status] lexon statusin.

subject, html dhe text plotësohen për çdo person nga kontakti i tij. {{firstName}} është fjala e parë e emrit të kontaktit, {{lastName}} pjesa tjetër, {{name}} emri i plotë, {{email}} adresa ku shkon kopja dhe {{unsubscribeUrl}} lidhja që e çregjistron.

Çdo fushë pranon një vlerë rezervë pas një vije, e përdorur kur kontakti nuk ka vlerë për të, ndaj {{firstName|there}} bëhet "there" për një kontakt të ruajtur pa emër. Vlerat maskohen në html, dhe çdo {{…}} tjetër lihet saktësisht siç është shkruar.

Jepni template: në vend të html: dhe text: për të dërguar një shabllon të ruajtur, si Hash me id dhe, sipas dëshirës, version, props dhe slots. Të njëjtat pesë vlera i mbërrijnë si props, por vetëm props që shablloni deklaron, ndaj një shabllon që deklaron firstName e merr atë, dhe një që nuk e deklaron nuk refuzohet kurrë për shkak të tij. Çdo gjë te props e tij shkon njësoj te çdo kopje.

Çdo kopje mban kokat e çregjistrimit me një klikim që i lejojnë një klienti poste të shfaqë butonin e vet të çregjistrimit, gjë që kërkojnë ofruesit e mëdhenj të kutive postare nga posta masive. Një trup html ose text që nuk e vendos vetë {{unsubscribeUrl}} merr një fundfaqe me një rresht me lidhjen. Një shabllon dërgohet saktësisht ashtu siç është, ndaj vendosni {{unsubscribeUrl}} në shabllon.

Çregjistrimi e shënon personin si të çregjistruar në çdo audiencë ku shkoi ai transmetim, dhe audiences.list_contacts e tregon këtë te unsubscribedAt i rreshtit të tij, siç përshkruan faqja e audiencave. Ai mbetet në audiencë dhe në librin e adresave, audiencat e tjera të tij nuk preken, dhe posta që i dërgohet një mesazh në herë vazhdon të dalë. Heqja nga audienca dhe shtimi sërish e bën përsëri të regjistruar.

Një transmetim arrin çdo kontakt në të paktën një nga audienceIds, një herë sado prej tyre ta mbajnë. Kapërcen një kontakt që është çregjistruar nga çdo prej atyre audiencave ku ndodhet, dhe një adresë në listën e bllokimit pas një kthimi ose ankese, ose sepse dikush e shtoi aty. Një kontakt i shtuar në një nga audiencat pas send, por para se dërgimi ta arrijë, përfshihet.

preview kthen të njëjtët numra pa dërguar: recipients, unsubscribed dhe suppressed. Një send që nuk do të arrinte askënd ngre 422 no_recipients si OpenEmail::ValidationError.

get i lexon counts drejtpërdrejt nga kopjet, ndaj pyeteni periodikisht ndërsa një transmetim dërgon, me sleep midis thirrjeve siç bën shembulli më lart. status kalon nga scheduled ose queued te sending dhe ngulet te sent pasi çdo kopje e dorëzuar ka dalë ose ka dështuar. Mbetet sending sa kohë që kopjet ende presin, edhe pasi completedAt thotë se u arrit personi i fundit. failed do të thotë se i gjithë transmetimi u ndal, dhe lastError tregon pse: nga adresa from nuk mund të dërgohet më, shablloni pushoi së zgjidhuri, plani mbaroi në mes të rrugës, vetë dërgimi vazhdoi të dështonte, ose nuk u shkrua dot asnjë kopje.

cancel ndal një transmetim që është scheduled, queued ose sending. Nuk shtohet askush tjetër dhe çdo kopje që pret ende anulohet, ndërsa kopjet që kanë dalë nuk mund të tërhiqen. Pasi ka dalë çdo kopje, cancel ngre 409 broadcast_not_cancellable si OpenEmail::ConflictError, dhe anulimi i një transmetimi të anuluar e kthen atë ashtu siç është.

list_recipients kthen një OpenEmail::Page me njerëzit te të cilët shkoi një transmetim, një rresht për çdo kopje, të renditur sipas adresës, me items, has_more? dhe next_cursor. list_all_recipients i përshkon të gjitha faqet në një Array të vetëm, dhe iterate_recipients ia jep kopjet një nga një një blloku, duke marrë faqen e radhës vetëm kur cikli e kërkon. Pa bllok kthen një Enumerator. limit: shkon nga 1 deri në 200, me 50 si parazgjedhje, dhe një cursor: jepet prapa me të njëjtat filter: dhe q:.

OpenEmail::BROADCAST_RECIPIENT_FILTERS emërton çdo filtër, dhe q: kërkon te adresa dhe emri, pa dalluar shkronjat e mëdha a të vogla. Hapjet dhe klikimet i lënë jashtë proxy-t e imazheve dhe skanuesit e lidhjeve, dhe mbeten 0 kur transmetimi u nis me gjurmimin të çaktivizuar.

get_recipient(id, email_id) kthen një kopje: i njëjti rresht, plus subject, html dhe text saktësisht siç i mori ai person, me fushat e bashkimit të plotësuara dhe lidhjen e vet të çregjistrimit. Jepni emailId e një rreshti si email_id. HTML-ja është nga para se të shtohej gjurmimi i hapjeve dhe klikimeve. Një email_id që nuk është kopje e këtij transmetimi ngre 404 recipient_not_found, dhe një transmetim i panjohur ngre 404 broadcast_not_found, të dyja si OpenEmail::NotFoundError.

stats kthen totalet dhe një seri. totals numëron kopjet sent, delivered, bounced, complained dhe failed, me pending për ato që ende presin, dhe personat që opened, clicked dhe unsubscribed, me opens dhe clicks si numërime ngjarjesh. series është e rrallë dhe nis nga më e vjetra, një interval për çdo grain: (minute, hour ose day, me parazgjedhje hour) në të cilin ndodhi diçka, i ndarë në zonën offset_minutes: në lindje të UTC. Jepni Time.now.utc_offset / 60 për zonën lokale. Ajo e numëron çdo person një herë, në herën e parë kur i ndodhi, ndaj shuma përputhet me totalet.

Jepini days: ose minutes: te stats për të lexuar edhe çfarë ndodhi së fundmi. Atëherë window numëron çfarë u dorëzua, u kthye, u raportua si spam, u hap, u klikua dhe u çregjistrua brenda saj, dhe series mban vetëm intervalet e saj, ndërsa totals mbulon ende gjithë transmetimin. Pa asnjërën prej tyre, window është nil.

send, get dhe cancel kthejnë secili një të tillë, një Hash me çelësa Symbol, dhe send shton replayed. list kthen një OpenEmail::Page me to, nga më i riu, dhe list_all e iterate përshkojnë çdo faqe. preview kthen një Hash me audienceIds, recipients, unsubscribed dhe suppressed. list_recipients kthen një OpenEmail::Page me rreshta marrësish, get_recipient kthen një rresht me përmbajtjen e tij, dhe stats kthen një Hash me broadcastId, grain, totals, window dhe series. analytics kthen një Hash me totals, series dhe një rresht për çdo transmetim te broadcasts. Kohët janë string-e ISO 8601, të cilat i analizon Time.iso8601.

Çdo rresht i list_recipients, list_all_recipients dhe iterate_recipients, si Hash me çelësa Symbol. Hash-i që kthen get_recipient shton subject, html dhe text.