Shabllonet, rregullat dhe webhook-et

Këto tri hapësira emrash e lënë një kuti postare të punojë pa e vëzhguar askush. templates ruan trupa që i dërgoni shumë herë, rules rendit postën ndërsa mbërrin, dhe webhooks i tregon serverit tuaj çfarë ndodhi. Çdo komandë është një metodë e SDK-së me emrin e saj në kebab-case, ndaj webhooks.rotateSecret është openemail webhooks rotate-secret, dhe lexon argumentet dhe flamujt si çdo komandë tjetër burimi.

Kjo faqe liston çdo komandë dhe atë që ia vlen të dihet para se ta përdorni në skript. Për çdo argument dhe flamur, me llojin e tij, fushëveprimet që i duhen, endpoint-in dhe çfarë kthen, ekzekutoni openemail <namespace> <verb> --help. Shtoni --json për të marrë të njëjtën faqe si JSON.

openemail templates --helpopenemail rules create --helpopenemail webhooks replay-delivery --help --json

Trupa të ruajtur një herë dhe të dërguar shumë herë, me versione, pamje paraprake dhe prop-e të tipizuara. Çdo komandë që merr <id-or-slug> pranon id-në tpl_ ose slug-un. Slug-u nuk ndryshon kurrë kur shablloni riemërtohet, ndaj fiksojeni slug-un në skripte.

• —Një shabllon i arkivuar refuzon të dërgojë me template_archived. publish e bën sërish aktiv.
• —Një hapësirë pune mban të shumtën 200 shabllone, përfshirë ato të arkivuara, ndaj fshirja është e vetmja mënyrë për të bërë vend.
• —delete refuzohet me template_in_use për sa kohë një transmetim i planifikuar ose në radhë e emërton ende shabllonin.

Kushte dhe veprime që vlerësohen mbi postën që mbërrin, në rendin që tregon rules list. Një rregull vepron vetëm mbi postën që mbërrin ndërsa ai është i aktivizuar. Asnjë komandë nuk e zbaton një rregull mbi postën që është tashmë në kutinë postare, dhe rules test është mënyra si shihni çfarë do të kapte. Id-të e rregullave nisin me rul_.

--conditions është një listë objektesh { field, op, value }, të bashkuara me --match all ose --match any, ku value është gjithmonë varg dhe negate: true e përmbys një kusht. --actions është një listë objektesh { type, value }, të zbatuara me radhë. Një rregull merr nga 1 deri në 20 kushte dhe nga 1 deri në 10 veprime, dhe një kuti postare mban të shumtën 100 rregulla.

• —Fushat e kushteve: from, from_domain, envelope_from, to, cc, bcc, recipient, reply_to, delivered_to, subject, body, header, list_id, attachment_name, attachment_type, has_attachment, attachment_size, message_size, spam, hour dhe weekday.
• —Operatorët: matches, contains, equals, starts_with, ends_with, gt dhe lt. gt dhe lt funksionojnë vetëm me fushat numerike, dhe has_attachment e spam pranojnë vetëm equals me true ose false.
• —Llojet e veprimeve: label, remove_label, archive, mark_read, star, spam, trash, forward, reply, block_sender dhe reject. label dhe remove_label marrin një id etikete si USER_RECEIPTS, forward merr një adresë dhe reply merr një id ose slug shablloni.
• —from_domain përputhet edhe me nëndomenet, dhe hour e weekday lexohen në UTC, me 0 për të dielën.
• —Një rregull me një veprim reject duhet të testojë edhe envelope_from, përndryshe refuzohet me reject_needs_envelope.

Endpoint-e në serverin tuaj që marrin ngjarje të nënshkruara të kutisë postare, me sekretet e tyre të nënshkrimit, regjistrin e dorëzimeve dhe një regjistër auditimi për çdo ndryshim. Id-të e endpoint-eve nisin me whe_ dhe id-të e dorëzimeve me whd_.

Lëreni jashtë --event-types dhe një endpoint merr grupin e parazgjedhur, ngjarjet email.* përveç email.replied. email.replied, ngjarjet domain.* dhe ngjarjet suppression.* e arrijnë vetëm kur i emërtoni. --address-allowlist dhe --domain-allowlist e ngushtojnë një endpoint në disa adresa ose domene, ashtu siç ngushtojnë një çelës API.

• —Një hapësirë pune mban 10 endpoint-e, përveç nëse mbështetja ia ka rritur kufirin.
• —Një endpoint që dështon 100 dorëzime radhazi fiket nga serveri, dhe webhooks update <id> --enabled e rikthen.
• —Me një hyrje me shfletues, vetëm pronari i hapësirës së punës mund të lexojë një dorëzim me get-delivery. Kushdo tjetër merr owner_only dhe kodin e daljes 4.

templates preview renderon saktësisht atë që do të prodhonte një dërgim me të njëjtat vlera, përfshirë draftet, dhe kërkon vetëm templates:read, ndaj edhe një çelës vetëm për lexim mund ta ekzekutojë. Një prop të detyrueshëm që mungon e raporton si paralajmërim aty ku send do ta refuzonte, ndaj dështojeni build-in për çdo paralajmërim. publish është i sigurt në çdo deploy, sepse publikimi i një head-i që është tashmë live nuk ndryshon asgjë.

draft=$(openemail templates get order-shipped --json | jq .latestVersion)openemail templates preview order-shipped --template-version "$draft" \  --props '{"orderId":"AC-4192","customer":"Ada"}' --json | jq -e '.warnings == []'openemail templates publish order-shipped

Fiksoni versionin, që një rishkrim i publikuar nesër të mos ndryshojë atë që dërgon ky kod, dhe jepni një çelës idempotence të marrë nga ajo që shkaktoi dërgimin, që një riprovim pas një përgjigjeje të humbur të riluajë mesazhin e parë në vend që të dërgojë një të dytë. --dry-run shtyp metodën, URL-në, header-at me kredencialin tuaj të fshehur dhe trupin, nuk dërgon asgjë dhe del me kodin 0. Ekzekutojeni sërish pa --dry-run për të dërguar.

openemail templates send order-shipped \  --from 'Acme <[email protected]>' \  --to [email protected] \  --template-version 5 \  --props '{"orderId":"AC-4192","customer":"Ada"}' \  --idempotency-key order-shipped:AC-4192 \  --dry-run

Krijojeni rregullin të fikur, bëni një ekzekutim provë mbi postën e fundit, dhe ndizeni sapo të kapë atë që donit. Me një hyrje me shfletues, rules create dhe rules update kërkojnë një kod verifikimi, të cilin një skript nuk mund ta shkruajë, ndaj ekzekutoni fillimisht openemail verify. Për 60 minutat e ardhshme ai profil i ekzekuton pa pyetur.

[  { "field": "from_domain", "op": "equals", "value": "stripe.com" },  { "field": "has_attachment", "op": "equals", "value": "true" }]

[  { "type": "label", "value": "USER_RECEIPTS" },  { "type": "archive" }]

openemail verifyrule=$(openemail rules create --name 'Stripe receipts' \  --conditions @conditions.json --actions @actions.json --no-enabled --json | jq -r .id)openemail rules test "$rule" --days 30 --limit 100openemail rules update "$rule" --enabled

Lexoni paralajmërimet e rules test para përputhjeve të tij. field_unevaluable do të thotë se një kusht lexon diçka që posta e ruajtur nuk e mbart më, ndaj testi nuk mund ta gjykonte, dhe forward_unverified do të thotë se një objektiv përcjelljeje nuk pritet këtu. wouldApply liston atë që deklaron rregulli: një përcjellje te një adresë që nuk ka konfirmuar dështon përsëri kur mbërrin posta e vërtetë.

rules reorder merr çdo rregull të kutisë postare saktësisht një herë. Një rregull i lënë jashtë ose i emërtuar dy herë refuzohet dhe asgjë nuk zhvendoset. rules list kthen id-të në rendin në të cilin ekzekutohen, ndaj vendoseni atë që doni të parin përpara të tjerëve.

first=rul_4f1c9a2b7d3e8f6a0b5c1d2eopenemail rules reorder "$first" $(openemail rules list --all --ndjson \  | jq -r --arg first "$first" 'select(.id != $first) | .id')openemail rules list-runs --thread-id CAHk7pQ2x9LmZ4 --json | jq '.items[] | {ruleName, actions, failures}'

list-runs është regjistri i asaj që ndodhi realisht. Çdo rresht është një rregull që përputhet me një mesazh, me veprimet që patën efekt dhe, te failures, ato që kutia postare i refuzoi, si një përgjigje te një dërgues që ka marrë tashmë përgjigje atë ditë. Çdo rresht mban emrin që kishte rregulli në atë kohë, ndaj --rule-id funksionon edhe për një rregull që e keni fshirë që atëherë.

webhooks create e tregon sekretin e nënshkrimit një herë, dhe asnjë komandë e mëvonshme nuk e tregon sërish. Me --json ai ndodhet në JSON-in në stdout, ndërsa kujtesa për ta ruajtur shkon në stderr, ndaj dalja mbetet e analizueshme. webhooks test dërgon një ngjarje sintetike të nënshkruar email.sent pavarësisht se në çfarë është abonuar endpoint-i, dhe nuk dërgohet asnjë postë.

openemail verifyopenemail webhooks create --url https://hooks.acme.com/openemail \  --event-types email.received,email.bounced,email.complained \  --description 'Support desk sync' --json > endpoint.jsonjq -r .secret endpoint.jsonopenemail webhooks test "$(jq -r .id endpoint.json)" --json | jq .deliveryrm endpoint.json

Vendoseni sekretin në depon tuaj të sekreteve para se të fshini skedarin. test del me kodin 0 edhe kur serveri juaj dështon, ndaj lexoni delivery.status: delivered për një përgjigje 2xx dhe failed për çdo gjë tjetër, përfshirë një ridrejtim, meqë ridrejtimet nuk ndiqen kurrë. Një responseCode me vlerë null do të thotë se nuk mbërriti fare përgjigje.

Pas një ndërprerjeje në anën tuaj, listoni çfarë dështoi në të gjitha endpoint-et, kontrolloni që një ridërgim do të pranohej, dhe dërgojeni sërish ngjarjen. Një ridërgim mbart të njëjtën id ngjarjeje, ndaj një marrës që hedh id-të që i ka trajtuar tashmë e trajton si ngjarjen që e njeh.

openemail webhooks list-workspace-deliveries --status failed --since 2026-09-26T00:00:00Z --all --ndjson \  | jq -r '[.endpointId, .id, .eventType, (.responseCode // "no answer")] | @tsv'openemail webhooks get-delivery whe_3f9c2a7b1e4d8f60a5c7b92d whd_8c1e4a7f2b9d3e6a0c5f1b28 --json | jq .replayRefusalopenemail webhooks replay-delivery whe_3f9c2a7b1e4d8f60a5c7b92d whd_8c1e4a7f2b9d3e6a0c5f1b28

• —--since dhe --until marrin një çast ISO 8601.
• —Një rresht i dështuar, nextAttemptAt i të cilit mban një kohë, ka ende një riprovim automatik që po vjen.
• —replayRefusal është null kur një ridërgim do të nisej, dhe përndryshe emërton pse do të refuzohej, si webhook_disabled ndërsa endpoint-i është i fikur.
• —Ridërgimet bëhen një ngjarje në një kohë. Asnjë komandë nuk i dërgon sërish të gjitha dorëzimet e dështuara.

Me një hyrje me shfletues, katër nga këto komanda kërkojnë një kod verifikimi para se të ndryshojnë ndonjë gjë, si aplikacioni web: rules create, rules update, webhooks create dhe webhooks update. Një çelësi API nuk i kërkohet kurrë. Çdo komandë tjetër në këtë faqe ekzekutohet pa kod, përfshirë fshirjet dhe webhooks rotate-secret.

• —Në terminal, CLI ju dërgon me email një kod gjashtëshifror, ose kërkon një nga aplikacioni juaj i autentikimit kur hyrja me dy hapa është aktive, pastaj e ekzekuton komandën një herë.
• —Pa mbikëqyrje, me --json ose --no-input, në CI ose pa terminal, askush nuk mund ta shkruajë kodin, ndaj komanda ndalet me kodin e daljes 4 dhe nuk ndryshon asgjë. Ekzekutoni fillimisht openemail verify, dhe profili nuk ka nevojë për kod për 60 minuta.
• —--yes konfirmon një fshirje, por nuk e kapërcen kurrë një kod.

Shtatë komanda këtu heqin ose mbishkruajnë diçka, ndaj kërkojnë fillimisht konfirmim: templates delete, templates delete-version, templates replace-content, templates restore-version, rules delete, webhooks delete dhe webhooks rotate-secret. Pa mbikëqyrje, secila ndalet me kodin e daljes 2 përveç nëse jepni --yes.

$ openemail webhooks delete whe_3f9c2a7b1e4d8f60a5c7b92d --no-input✗ Refusing to run unattended. Pass --yes to confirm.$ openemail webhooks delete whe_3f9c2a7b1e4d8f60a5c7b92d --yes

--dry-run shtyp kërkesën e parë që do të ndryshonte diçka dhe del me kodin 0, pa e dërguar dhe pa ju kërkuar konfirmim. Me --json shtyp një dokument të vetëm { dryRun, request }. rules test, templates render dhe templates preview nuk ndryshojnë asgjë, por janë kërkesa POST, ndaj një ekzekutim provë i shtyp në vend që t'i ekzekutojë.

• —templates list, templates list-versions, rules list, rules list-runs dhe çdo komandë webhooks list… lexojnë një faqe në një kohë, 25 rreshta përveç nëse --limit kërkon deri në 100. Një terminal tregon --cursor që duhet dhënë për faqen tjetër.
• —--all lexon çdo faqe, --max <n> ndalet pas aq rreshtave, dhe --ndjson shtyp një objekt JSON për rresht. Me --json, një listë shtyp një dokument të vetëm { items, hasMore, nextCursor }, përfshirë me --all.
• —Ktheni një kursor me të njëjtët filtra dhe renditje me të cilët erdhi. Çdo gjë tjetër refuzohet si invalid_cursor, me kodin e daljes 7.
• —templates list-sends i ndan faqet sipas numrit në vend të kësaj, me --page dhe --page-size, raporton total, dhe nuk ka --all. Numrat e faqeve zhvendosen ndërsa posta po niset, ndaj ngushtoni dritaren kohore me --days ose --minutes në vend që të shkoni thellë nëpër faqe.
• —templates list-starters dhe templates list-fonts kthejnë gjithë katalogun njëherësh, dhe rules reorder kthen çdo rregull si një listë të thjeshtë në rendin e tij të ri.
• —Një kuti postare mban të shumtën 100 rregulla, ndaj rules list --limit 100 kthen gjithmonë çdo rregull në një faqe.

• —--template-version është fusha e trupit version, e riemërtuar sepse --version shtyp versionin e CLI-së. Argumenti <version> i get-version, restore-version dhe delete-version është një numër versioni, jo një id tplv_.
• —--conditions, --actions, --document, --slots, --props dhe flamujt e tjerë JSON marrin JSON në rresht, nga një skedar me @path, ose nga stdin me -. --data merr gjithë trupin në të njëjtën mënyrë, dhe çdo flamur që jepni gjithashtu e mbishkruan çelësin e vet.
• —--html merr vetë markup-in, jo një skedar, ndaj --html @page.html dërgon tekstin @page.html. Jepni --html "$(cat page.html)", ose vendoseni html në skedarin që i jepni --data.
• —rules update --conditions dhe --actions zëvendësojnë gjithë listën, po ashtu edhe webhooks update --event-types, --address-allowlist dhe --domain-allowlist. Lexoni vlerën aktuale, ndryshojeni dhe dërgojeni të gjithën.
• —Një --event-types bosh është gabim përdorimi. Për ta kthyer një endpoint te grupi i parazgjedhur, dërgoni --data '{"eventTypes":[]}', dhe për të ndalur dorëzimet e tij, jepni --no-enabled.
• —--expected-version te templates update, replace-content dhe restore-version merr versionin head që lexuat. Kur dikush tjetër e ka lëvizur head-in që atëherë, komanda ndalet me kodin e daljes 6 dhe version_conflict, dhe nuk shkruan asgjë.
• —rules update <id> --no-enabled e fik një rregull dhe ia mban vendin në rend, që është mënyra për ta ndalur përkohësisht një rregull pa e fshirë.