PHP

Dërgoni një grup

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

emails->sendBatch

send_batch.php

$invoices = [    ['number' => 'INV-1042', 'email' => '[email protected]'],    ['number' => 'INV-1043', 'email' => '[email protected]'],]; $messages = []; foreach ($invoices as $invoice) {    $messages[] = [        'from' => '[email protected]',        'to' => $invoice['email'],        'subject' => 'Invoice ' . $invoice['number'],        'text' => 'Your invoice is attached.',    ];} $result = $client->emails->sendBatch($messages, idempotencyKey: 'invoices:2026-09'); echo $result->sent, ' sent, ', $result->failed, ' failed', PHP_EOL; foreach ($result as $item) {    if ($item['status'] === 'error') {        error_log($item['index'] . ' ' . $item['error']['code'] . ' ' . $item['error']['message']);    } else {        echo $item['index'], ' ', $item['email']['id'], PHP_EOL;    }}

sendBatch merr një listë array-sh mesazhesh, secili me formë saktësisht si array-i që merr emails->send, dhe kthen një OpenEmail\Result\BatchResult. items e tij mbajnë një array 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, dhe një cikël mbi rezultatin i përshkon ato. 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ëjtën listë 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 hedh përjashtim. Hedh përjashtim vetëm një problem me grupin në tërësi: një listë 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->sendBatch

emailsarraye 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ë `DateTimeInterface` bëhet çast, bajtet e bashkëngjitjeve kodohen, dhe një element që nuk është array hedh `InvalidArgumentException` para se të dërgohet çfarëdo. Një listë 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ë `idempotencyKey:` i keqformuar e refuzojnë gjithashtu të gjithë thirrjen, para se të dërgohet qoftë edhe një mesazh.
idempotencyKeystring: 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.
apiKeystring: E dërgon grupin me këtë çelës në vend të atij të klientit.

Çdo mesazh në emails

fromstring or arraye detyrueshme: Dërguesi, si adresë e zhveshur, `Name <addr@host>` ose një array 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 or arraye detyrueshme: Të paktën një marrës, dhe një marrës i vetëm mbështillet nga klienti në një listë. 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 or array: Parazgjedhja është asnjë, dhe numërohet te i njëjti total prej 50 adresash si `to` dhe `bcc`.
bccstring 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 array: 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ë, me më së shumti një milion karaktere. Të dyja mund të dërgohen, dhe çdo transport në këtë rrugë ndërton një trup të vetëm nga një string i vetëm, pra `html` fiton aty ku ka një të tillë.
headersarray: 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: 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 një stream nga `fopen`, një `SplFileInfo` ose një stream PSR-7 dhe klienti e lexon dhe e kodon, ose një string që është tashmë base64. Një array 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.
templatearray: 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.
scheduledAtDateTimeInterface or string: Një `DateTimeInterface`, 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ë string date pa orë 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.
cancellableForSecondsint: 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.
trackingarray: `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.
tagsarray: 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:`, `broadcastId:` 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ë.
translatearray: 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\Result\BatchResult

Rezultati është vetëm për lexim, IteratorAggregate mbi items dhe Countable, ndaj foreach ($result as $item) i përshkon elementet dhe count($result) i numëron.

itemsarray: Një array 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.
sentint or null: 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. Është null vetëm kur përgjigjja nuk mbarti numër.
failedint or null: 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

indexint: Pozicioni që mbante mesazhi i këtij elementi në listë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.
emailarray: 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.
errorarray: 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 specifik: `from_address_forbidden`, `invalid_email_address`, `too_many_recipients`, `reserved_header`, `message_too_large`, `unknown_parameter`. Bashkësi e hapur që zgjerohet, ndaj një kod që nuk e njihni trajtojeni sipas `type` të tij. Këtu quhet `code` sepse ky është zarfi i dekoduar, ndërsa një përjashtim e mbart të njëjtën vlerë si `errorCode`.
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`.