Ruby

Dërgoni një grup

`emails.send_batch`: deri në 100 mesazhe, rezultate për çdo element.

emails.send_batch

send_batch.rb

invoices = [  {number: "INV-1042", email: "[email protected]"},  {number: "INV-1043", email: "[email protected]"}] messages = invoices.map do |invoice|  {from: "[email protected]", to: invoice[:email], subject: "Invoice #{invoice[:number]}", text: "Your invoice is attached."}end result = client.emails.send_batch(messages, idempotency_key: "invoices:2026-09") puts "#{result.sent} sent, #{result.failed} failed" result.items.each do |item|  if item[:status] == "error"    warn "#{item[:index]} #{item.dig(:error, :code)} #{item.dig(:error, :message)}"  else    puts "#{item[:index]} #{item.dig(:email, :id)}"  endend

send_batch merr një Array Hash-esh mesazhesh, secili me formë saktësisht si trupi i emails.send, dhe kthen një OpenEmail::BatchResult. items e tij mbajnë një Hash për çdo mesazh, sipas radhës, secili ose ok me mesazhin e vet, ose error me zarfin me të cilin do të ishte refuzuar ai mesazh. Asgjë nuk kthehet pas, ndaj një numër failed mbi 0 është një listë për të vepruar dhe jo arsye për ta ridërguar grupin.

Një çelës idempotence i vetëm e mbulon grupin, dhe serveri e zgjeron atë për çdo element, ndaj një grup i riprovuar e riluan çdo mesazh në vend që t’i shkrijë të gjitha te i pari. Dërgoni të njëjtin Array në të njëjtën radhë kur e riprovoni: një element që lëvizi lidhet me çelësin e një pozicioni tjetër dhe kthehet si gabim idempotency_key_reuse.

Një mesazh i refuzuar nuk ngre gabim. Ngre gabim vetëm një problem me grupin në tërësi: një Array bosh, më shumë se 100 mesazhe, më shumë se 10 që mbartin translate, një dështim çelësi ose fushe, ose një defekt i serverit. Një defekt i serverit në mes të rrugës vjen pasi elementet e mëparshme kanë ikur, dhe klienti e riprovon me të njëjtin çelës, gjë që i riluan ato elemente në vend që t’i dërgojë dy herë.

Elementet dërgohen njëri pas tjetrit brenda një kërkese të vetme, ndaj një grup i madh dërgimesh të menjëhershme zgjat dukshëm më shumë se një send i vetëm. Mbajeni timeout: e klientit bujar.

Parametrat: emails.send_batch

emailsArray<Hash>e detyrueshme: Nga 1 deri në 100 mesazhe, të dërguar si `{"emails": [...]}` dhe të pranuar një nga një sipas radhës së dhënë. Secili kalon nga i njëjti trajtim si `emails.send`, ndaj një marrës i vetëm mbështillet, një Time bëhet çast dhe bajtet e bashkëngjitjeve kodohen. Një Array bosh, më shumë se 100, ose më shumë se 10 mesazhe që mbartin `translate` e refuzojnë të gjithë thirrjen me një `validation_error` te `emails`. Mungesa e fushës `emails:send` dhe një `idempotency_key:` i keqformuar e refuzojnë gjithashtu të gjithë thirrjen, para se të dërgohet qoftë edhe një mesazh.
idempotency_keyString: Shmang dyfishimin e grupit mes proceseve. Klienti, sido që të jetë, i bashkëngjit çdo thirrjeje një çelës të sapogjeneruar, ndaj riprovat e tij nuk dërgojnë kurrë dy herë, dhe serveri e zgjeron çelësin që merr për çdo element si `key/0`, `key/1` e kështu me radhë, të ndarë me slash, një karakter që çelësi juaj nuk mund ta përmbajë, ndaj një çelës i vetëm për njëqind mesazhe nuk mund t’i shkrijë ato te i pari.
api_keyString: E dërgon grupin me këtë çelës në vend të atij të klientit.

Çdo mesazh në emails

fromString or Hashe detyrueshme: Dërguesi, si adresë e zhveshur, `Name <addr@host>` ose një Hash me `email` dhe `name`. Nuk ka dërgues rezervë, dhe çelësi duhet ta ketë të lejuar këtë adresë. Një refuzim e dështon vetëm atë element, si një `permission_error` me kodin `from_address_forbidden`.
toString, Hash or Arraye detyrueshme: Të paktën një marrës, dhe një marrës i vetëm mbështillet nga klienti në një Array. Më së shumti 50 adresa gjithsej në `to`, `cc` dhe `bcc`, të numëruara për çdo mesazh dhe jo për gjithë grupin.
ccString, Hash or Array: Parazgjedhja është asnjë, dhe numërohet te i njëjti total prej 50 adresash si `to` dhe `bcc`.
bccString, Hash or Array: Parazgjedhja është asnjë, dhe numërohet te i njëjti total prej 50 adresash. `Bcc` është një nga emrat që `headers` nuk mund t'i caktojë, pra kjo është e vetmja mënyrë për një kopje të fshehtë. Forma me header do të prishte zarfin për çdo marrës që e mban adresën të fshehur.
replyToString or Hash: Ku shkojnë përgjigjet. Zbatohet pas `headers`, kështu që mbishkruan një `Reply-To` që e keni caktuar edhe atje në vend që të shtojë një të dytë.
subjectString: Më së shumti 998 karaktere, kufiri i rreshtit sipas RFC 5322, dhe si parazgjedhje është një String bosh. Një temë bosh kalon te tema e vetë shabllonit kur `template` siguron një të tillë.
htmlString: Pjesa HTML, me më së shumti një milion karaktere, dhe pjesa që shohin marrësit kur jepen të dy trupat. Kërkohet një nga `html`, `text`, `template` ose `draftId`, dhe një element pa asnjërin prej tyre dështon si `validation_error` mbi `html`.
textString: Pjesa me tekst të thjeshtë, më së shumti një milion karaktere. Mund të dërgohen të dyja, por çdo transport në këtë rrugë ndërton një trup nga një String i vetëm, ndaj fiton `html` kur ka një të tillë.
headersHash: Vetëm `X-*`, `List-*`, Reply-To, Precedence, Auto-Submitted, Importance, Priority dhe Feedback-ID. Çdo gjë që e vendos vetë transporti (From, To, Bcc, Subject, Message-ID, header-at DKIM dhe ARC) refuzohet si `reserved_header` në vend që të hidhet në heshtje. Vlerat kanë më së shumti 998 karaktere dhe nuk mund të mbartin CR, LF ose NUL, sepse një rresht i dytë është një header i dytë.
attachmentsArray<Hash>: Më së shumti 20 skedarë për mesazh, me skedarë inline gjithsej 5 MB pas dekodimit, të numëruar për mesazh dhe jo për grup. `content` është base64 në rrjet. Jepni bajtet si String binar, IO ose Pathname dhe klienti i kodon. Një Hash vetëm me `fileId` emërton një skedar që gjendet tashmë në hapësirën e punës dhe nuk llogaritet te kufiri i skedarëve inline.
threadIdString: Përgjigjuni brenda një thread-i ekzistues, me më së shumti 256 karaktere. Transporti shkruan In-Reply-To dhe References prej saj, që është ajo që e bën përgjigjen të ulet brenda bisedës dhe jo pranë saj.
draftIdString: Dërgoni përmbajtjen e një drafti të ruajtur nën këtë zarf; më së shumti 256 karaktere. Në rrjet shkojnë marrësit, tema dhe header-at e ndërtuar këtu.
templateHash: Përpunon në server një shabllon të ruajtur, sipas id-së (`tpl_…`) ose slug-ut, ku `version` fikson një rishikim dhe `props` e `slots` e mbushin. Përcaktohet një herë, kur pranohet elementi, dhe refuzohet bashkë me `html` ose `text` dhe bashkë me `draftId`, sepse secili prej tyre është një përgjigje e dytë për atë që përmban mesazhi.
scheduledAtTime, DateTime or String: Një Time ose DateTime, një çast ISO 8601 ose një kohëzgjatje si `PT1H`, të paktën një sekondë në të ardhmen dhe më së shumti 365 ditë përpara. Një Date e Ruby-t do të thotë mesnatë UTC e asaj dite. Elementet planifikohen në mënyrë të pavarur, ndaj një grup mund të mbajë njëqind kohë dërgimi të ndryshme.
cancellableForSecondsInteger: Një dritare anulimi në sekonda për një dërgim të menjëhershëm, nga 0 deri në 900, me 0 si parazgjedhje. Çdo vlerë mbi 0 refuzohet bashkë me `scheduledAt` në të njëjtin element, sepse një mesazh i planifikuar është tashmë i anulueshëm derisa të niset.
trackingHash: `opens` dhe `clicks`, secili opsional dhe secili që mbishkruan cilësimin vetëm për këtë mesazh. Një çelës që e lini jashtë ndjek adresën nga e cila dërgohet mesazhi (ose catch-all që e kapi), e cila është e fikur përveç nëse ajo adresë e ka ndezur.
tagsHash: Më së shumti 10 etiketa, me çelësa nga 1 deri në 64 karaktere të marrë nga `A-Za-z0-9_-` dhe me vlera deri në 256. Kthehen ashtu siç janë te mesazhi dhe nuk interpretohen kurrë: `emails.list` filtron sipas `status:`, `from:`, `broadcast_id:` dhe dritares së planifikimit, dhe asgjë tjetër, ndaj një etiketë është diçka për t’u lexuar nga një mesazh që e keni tashmë dhe jo një mënyrë për ta gjetur atë.
translateHash: Dërgojeni këtë element në një gjuhë tjetër, të përcaktuar në kohën e pranimit, që fjalët e miratuara të jenë fjalët që nisen. Më së shumti 10 elemente në një grup mund ta mbartin: secili harxhon disa thirrje modeli dhe elementet ekzekutohen sipas radhës, ndaj një grup më i madh do të ndërpritej në mes të dërgimit. Mbi këtë, e gjithë thirrja refuzohet si `too_many_items` te `emails`, para se të dërgohet çfarëdo.

Përgjigjja: OpenEmail::BatchResult

itemsArray<Hash>: Një Hash për çdo mesazh, në radhën që i dërguat. Asgjë nuk kthehet pas, ndaj ky është një regjistër i asaj që ndodhi me çdo mesazh dhe jo një raport mbi një transaksion. API-ja përgjigjet 207 qoftë kur u pranuan të gjitha mesazhet, disa prej tyre apo asnjëri, ndaj thirrja kthehet në çdo rast dhe degëzimi bëhet sipas `status` të secilit element.
sentInteger: Sa elemente u PRANUAN, gjë që nuk është e njëjtë me sa u nisën. Një element mund të jetë `ok` dhe prapë të mbartë një `email` me `status` `failed` ose `partial`, sepse një transport që e refuzon mesazhin pasi rreshti ekziston është një rezultat dërgese dhe jo një kërkesë e refuzuar.
failedInteger: Sa elemente mbartin një `error`. Një numër mbi 0 është një listë për të vepruar dhe jo arsye për ta ridërguar grupin. Mesazhet e pranuara kanë ikur tashmë.

Çdo element

indexInteger: Pozicioni që mbante mesazhi i këtij elementi në Array-n që dërguat. Mbartet si çelës, jo vetëm si radhë, ndaj kodi që filtron ose rendit `items` mund të thotë prapëseprapë cili mesazh dështoi.
statusString: `ok` ose `error`. `ok` mbart `email`, `error` mbart `error`, dhe asnjë element nuk i mbart të dyja.
emailHash: Mesazhi i pranuar, vetëm te një element `ok`, në të njëjtën formë që kthen një dërgim i vetëm. `replayed` i tij është true kur `Idempotency-Key` i derivuar përputhej me një dërgim që ekzistonte tashmë, ndaj nuk u dërgua asgjë e re dhe ky është mesazhi origjinal. Nuk mbart çelës `tracking`, sepse angazhimi raportohet më vonë dhe në kohën e pranimit nuk ka asgjë për të raportuar.
errorHash: Pse u refuzua ky mesazh i vetëm, vetëm te një element `error`. Është zarfi i gabimit të API-së pa `docUrl` dhe `requestId`: këto përshkruajnë kërkesën, dhe kërkesa në tërësi pati sukses.

Gabimi i një elementi

typeString: Kategoria sipas së cilës degëzoni: `validation_error`, `permission_error`, `not_found_error`, `conflict_error` dhe të tjerat. Bashkësia është e ngrirë dhe nuk do të rritet, ndryshe nga `code`.
codeString: Dështimi konkret: `from_address_forbidden`, `invalid_email_address`, `too_many_recipients`, `reserved_header`, `message_too_large`, `unknown_parameter`. E hapur dhe shtuese, prandaj trajtojeni një kod që nuk e njihni si `type`-in e tij.
messageString: Një fjali e shkruar për një person, që emërton vlerën problematike aty ku ka një të tillë. Jo një identifikues i qëndrueshëm. Degëzoni mbi `code`.
paramString: Fusha që u refuzua, si një shteg me pika brenda ATIJ mesazhi: `to.0`, `from`, `attachments`. Mungon kur dështimi nuk emërton asnjë fushë, dhe nuk merr kurrë si prefiks pozicionin në batch, për të cilin shërben `index`.