مخاطبان، فهرست‌های مخاطب و ارسال‌های گروهی

چهار فضای نام کسانی را که برایشان می‌نویسید پوشش می‌دهند. مخاطبان دفترچهٔ نشانی فضای کاری‌اند، فهرست‌های مخاطب فهرست‌های نام‌داری از مخاطبان‌اند، ارسال گروهی یک پیام را برای همهٔ اعضای چند فهرست مخاطب می‌فرستد، و فهرست توقیف نشانی‌هایی را نگه می‌دارد که فضای کاری به آن‌ها نامه نمی‌فرستد. هر فرمان یک متد SDK را فرا می‌خواند، پس صفحه‌های SDK همان فراخوانی‌ها را با عمق بیشتری شرح می‌دهند.

• —مخاطب شناسه ندارد. نشانی‌اش کلیدی است که هر فرمان contacts می‌گیرد، با فاصله‌های اضافی حذف‌شده و حروف کوچک، پس [email protected] و [email protected] یک مخاطب‌اند. فهرست مخاطب شناسهٔ aud_ دارد، ارسال گروهی شناسهٔ brd_، و توقیف همان شناسه‌ای که suppressions list چاپ می‌کند.
• —هر مخاطب تا وقتی وجود دارد در فهرست مخاطب پیش‌فرض است. آن فهرست را نمی‌توان حذف، خالی یا کوچک کرد، و builtin در آن برابر default است.
• —دفترچهٔ نشانی از آنِ فضای کاری است، پس همهٔ اعضا و همهٔ کلیدها همان یک دفترچه را می‌خوانند و در آن می‌نویسند.
• —هر فضای نام به شکل مفردش هم پاسخ می‌دهد، مانند openemail contact get، و نام‌های مستعار معمول کار می‌کنند: ls، show، new، edit و rm. در suppressions که فعل‌هایش add و remove است، new به add و rm به remove می‌رسد.

دفترچهٔ نشانی فضای کاری: کسانی که یک عضو از نامه‌نگار برنامه برایشان نوشته، به‌علاوهٔ هر کسی که دستی ذخیره شده است. نامهٔ رسیده کسی را اضافه نمی‌کند، ارسال از طریق API یا CLI هم همین‌طور.

فهرست‌های نام‌داری از مخاطبان، تا 100 فهرست در هر فضای کاری. نشانی باید پیش از پیوستن به یکی از آن‌ها مخاطب باشد، مگر از طریق import-contacts که نشانی‌های تازه را در همان حین ذخیره می‌کند.

یک پیام برای همهٔ اعضای حداکثر 10 فهرست مخاطب، که برای هر نفر نسخه‌ای جداگانه فرستاده می‌شود، با فیلدهای ادغامِ پرشده و یک پیوند لغو اشتراک. هر نسخه یک ایمیل معمولی است با شناسهٔ msg_، رویدادها و وب‌هوک‌های خودش.

نشانی‌هایی که این فضای کاری به آن‌ها نامه نمی‌فرستد: برگشت‌های سخت و شکایت‌ها، که همان لحظه ثبت می‌شوند، و هر نشانی‌ای که دستی اضافه کنید. ارسال به یکی از آن‌ها برای آن گیرنده پیش از بیرون رفتن هر چیزی رد می‌شود.

بیشتر فرمان‌ها به دامنهٔ مجوز خواندن یا نوشتن فضای نامشان نیاز دارند. چندتایی دامنهٔ دیگری لازم دارند، چون چیز دیگری را می‌خوانند یا تغییر می‌دهند:

• —کلیدی که به نشانی‌ها یا دامنه‌های مشخصی محدود است همان دفترچهٔ نشانی‌ای را می‌خواند و در آن می‌نویسد که هر کلید دیگری. فقط ارسال‌های گروهی‌ای را می‌بیند که از نشانی یا دامنه‌ای که دارد فرستاده شده‌اند، از list-people فقط مخاطبان ذخیره‌شده را می‌گیرد، و contacts list-threads، activity، block و unblock، و نیز suppressions add و remove آن را با 422 capability_unsupported رد می‌کنند.
• —ورود با مرورگرِ عضوی که فقط به برخی نشانی‌ها دسترسی دارد در همهٔ فرمان‌های contacts، audiences و broadcasts با 422 capability_unsupported رد می‌شود. suppressions add ورود با مرورگرِ هر کسی جز مالک فضای کاری را رد می‌کند.

یک فهرست مخاطب را از یک فایل بسازید، سپس بشمارید که یک ارسال گروهی به آن به چه کسانی می‌رسد. import-contacts نشانی‌هایی را که هنوز مخاطب نیستند ذخیره می‌کند، و اجرای دوباره‌اش هیچ چیز را دو بار نمی‌سازد یا اضافه نمی‌کند.

[  { "email": "[email protected]", "name": "Ada Lovelace" },  { "email": "[email protected]", "name": "Grace Hopper" },  { "email": "[email protected]" }]

AUDIENCE=$(openemail audiences create --name 'Product updates' --json | jq -r .id)openemail audiences import-contacts "$AUDIENCE" --contacts @contacts.jsonopenemail broadcasts preview --audience-ids "$AUDIENCE"

یک ارسال گروهی را با --dry-run بررسی کنید، که درخواست را چاپ می‌کند و چیزی نمی‌فرستد، سپس آن را بفرستید. ارسال گروهی بی‌درنگ ساخته و در پس‌زمینه فرستاده می‌شود، پس برای دنبال کردنش get را پیاپی بپرسید. این بدنه {{unsubscribeUrl}} را جایی نمی‌گذارد، پس هر نسخه یک پانویس یک‌خطی لغو اشتراک می‌گیرد.

{  "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>",  "scheduledAt": "2026-10-01T09:00:00Z"}

openemail broadcasts send --data @broadcast.json --dry-runBROADCAST=$(openemail broadcasts send --data @broadcast.json --yes --json | jq -r .id)openemail broadcasts get "$BROADCAST"openemail broadcasts stats "$BROADCAST" --grain day

ببینید یک ارسال گروهی به چه کسانی نرسید. --ndjson در هر سطر یک گیرنده چاپ می‌کند و --all --json یک سند با همهٔ صفحه‌ها.

openemail broadcasts list-recipients brd_5a8c1e3f7b2d94a06c8e1f3b --filter bounced --ndjson | jq -r .emailopenemail broadcasts list-recipients brd_5a8c1e3f7b2d94a06c8e1f3b --filter not_opened --all --json | jq ".items | length"openemail suppressions list --reason bounce --all --max 50

اعضای مشترک یک فهرست مخاطب را در فهرستی دیگر کپی کنید. jq جریان را به بدنه‌ای که add-contacts می‌گیرد تبدیل می‌کند و --data - آن را از stdin می‌خواند. --max 200 آن را به 200 نشانی‌ای محدود می‌کند که یک فراخوانی می‌پذیرد.

openemail audiences list-contacts aud_9f2c4b7e1a0d63d84c5f2e7b --statuses subscribed --max 200 --ndjson \  | jq -s '{ emails: map(.email) }' \  | openemail audiences add-contacts aud_1c4e7a9b2d0f36e85a7c1b4d --data -

همهٔ مخاطبانی را که نامه‌نگار در یک دامنه ثبت کرده حذف کنید. delete-many در هر فراخوانی تا 200 نشانی می‌گیرد، پس xargs -n 200 فهرست بلندتر را تقسیم می‌کند. دسته‌ها را نخست با --dry-run بررسی کنید، چون بازگشتی در کار نیست.

openemail contacts list --source auto --all --ndjson \  | jq -r 'select(.email | endswith("@old-vendor.example")) | .email' > leaving.txtxargs -n 200 openemail contacts delete-many --dry-run < leaving.txtxargs -n 200 openemail contacts delete-many --yes < leaving.txt

فرستادن به یک نشانی را متوقف کنید، دوباره به یکی اجازه دهید و یک فرستنده را مسدود کنید. removable می‌گوید suppressions remove کدام ردیف‌ها را برمی‌دارد.

openemail suppressions add --email [email protected]openemail suppressions list --q [email protected] --json | jq -r '.items[] | select(.removable) | .id'openemail suppressions remove 7b1e2c3d-4f5a-4b6c-8d7e-9f0a1b2c3d4e --yesopenemail contacts block [email protected]

این فرمان‌ها پیش از اجرا در ترمینال از شما تأیید می‌خواهند:

• —--yes به جای شما تأیید می‌کند. بدون نظارت، با --json یا --no-input، در CI یا بدون ترمینال، فرمانی که می‌پرسید با Refusing to run unattended. Pass --yes to confirm. و کد خروج 2 متوقف می‌شود.
• —--dry-run درخواستی را که فرمان می‌فرستاد چاپ می‌کند و بدون پرسیدن و بدون تغییر هیچ چیز با کد 0 خارج می‌شود.
• —با ورود از طریق مرورگر، audiences delete نخست کد تأیید هویت می‌خواهد، همان‌طور که برنامهٔ وب. --yes هرگز از آن نمی‌گذرد و بدون نظارت فرمان با کد خروج 4 متوقف می‌شود. از پیش openemail verify را اجرا کنید، یا از کلید API استفاده کنید که هرگز از آن پرسیده نمی‌شود.
• —audiences empty هرگز کد تأیید هویت نمی‌خواهد، پس پیش از دادن --yes شناسه را بررسی کنید.

هر فرمانی که فهرست می‌کند یک صفحه می‌خواند. وقتی موارد بیشتری مانده باشد، نشانگری را که چاپ کرده با همان فیلترها به --cursor بدهید، یا همه را بخوانید:

• —--all همهٔ صفحه‌ها را می‌خواند و موارد را جریانی می‌فرستد: در ترمینال یک جدول، و وقتی به لوله داده شود یا با --ndjson در هر سطر یک شیء JSON.
• —--max <n> پس از همان تعداد مورد می‌ایستد و --all را هم در بر دارد.
• —--json یک سند { items, hasMore, nextCursor } چاپ می‌کند، با --all هم.
• —نشانگرِ بدشکل یا کهنه 400 invalid_cursor می‌دهد. بدون آن از نو شروع کنید.

• —contacts create نشانی‌ای را که از پیش در دفترچه هست با 409 contact_exists رد می‌کند، پس تلاش دوباره هرگز نامی را که کسی ویرایش کرده بازنویسی نمی‌کند. contacts save هرگز رد نمی‌کند: نشانی را ذخیره می‌کند، نگه می‌دارد یا برمی‌گرداند، وضعیتش هر چه باشد.
• —contacts delete نشانی‌ای را هم که فقط در نامه‌ها دیده شده می‌پذیرد، که آن شخص را از list-people بیرون می‌برد. نامه‌ها می‌مانند. بازگشتی در کار نیست: ذخیرهٔ دوبارهٔ نشانی مخاطبی بی‌نام، بی‌یادداشت و بدون هیچ فهرستی جز فهرست پیش‌فرض می‌سازد.
• —نشانی هویت مخاطب است، پس contacts update نمی‌تواند آن را تغییر دهد. جابه‌جایی مخاطب یک delete و یک create است.
• —contacts set-photo تصویر را از یک فایل، یا از stdin با - می‌خواند. --content-type را بدهید، مانند image/jpeg: بدون آن تصویر ممکن است به‌صورت application/octet-stream برود که سرور آن را با 422 invalid_image رد می‌کند.
• —broadcasts send --scheduled-at زمانی به قالب ISO 8601 مانند 2026-10-01T09:00:00Z، یا مدتی به قالب ISO 8601 مانند PT2H یا P1D، تا 365 روز بعد می‌پذیرد. تأخیرهای کوتاهی که send --at می‌پذیرد، مانند 2h، اینجا رد می‌شوند.
• —فیلدهای ادغام در --subject، --html و --text کار می‌کنند: {{firstName}}، {{lastName}}، {{name}}، {{email}} و {{unsubscribeUrl}}، هر کدام با مقدار جایگزینی پس از یک خط عمودی، مانند {{firstName|there}}. بدنه‌ای که {{unsubscribeUrl}} را جایی نگذارد یک پانویس یک‌خطی لغو اشتراک می‌گیرد. قالب همان‌طور که هست فرستاده می‌شود، پس پیوند را در قالب بگذارید.
• —ارسال گروهی پیش از نوشتن هر چیزی با ارسال‌های ماهانهٔ طرح سنجیده می‌شود، و هر نسخه یک ارسال شمرده می‌شود. ارسالی که سهمیه کفافش را ندهد با 429 send_quota_exceeded رد می‌شود و چیزی از آن باقی نمی‌ماند.
• —وقتی ممکن است اسکریپتی آن گام را دوباره اجرا کند، --idempotency-key خودتان را به broadcasts send بدهید. همان کلید به جای فرستادن ارسال گروهی تازه، با همان ارسالی که ساخته پاسخ می‌دهد.
• —مخاطبی که اشتراکش را در یک ارسال گروهی لغو کند با unsubscribedAt تنظیم‌شده در فهرست می‌ماند، و ارسال‌های گروهی بعدی به آن فهرست از او می‌گذرند. audiences list-contacts --statuses unsubscribed آن‌ها را فهرست می‌کند.
• —برگشت سخت در فهرست توقیف می‌ماند. suppressions remove آن را با 409 suppression_not_removable رد می‌کند و removable در هر ردیف این را از پیش می‌گوید.