پایگاه دانش
REST API
یک API روی HTTP با مستندات، و کلیدهایی که میتوان صادر، محدود به scope و باطل کرد.
جزئیات
- روشن، همهجا. این API در 68 مسیر، 104 عملیات مستندشده را ارائه میکند (ایمیلها، رشتهها، پیشنویسها، برچسبها، مخاطبان، مخاطبان هدف، دامنهها، قالبها، قواعد، نقشها، اعضا، تنظیمات، تقویم، ردیابی، وبهوکها و حساب) پشت یک سند OpenAPI 3.1 که به آن متعهدیم و میتوانید بدون کلید در GET /openapi.json بخوانیدش. دسترسی را کلید فضای کاریای تعیین میکند که در تنظیمات صادر میکنید.
- ماندگاریای که این بخش منتظرش بود تمام شده است. یک ارسال پیش از آنکه چیزی روانه شود یک ردیف مینویسد، با یک شناسهی عمومی به شکل msg_ و پس از آن 24 رقم hex، و GET /emails/{id} آن را برمیگرداند، در کنار /events برای رد پای هر گیرنده و /tracking برای بازشدنها و کلیکها. یک Idempotency-Key با 1 تا 255 نویسه روی یک ایندکس یکتا از کلید و کلید API شما با هم ثبت میشود، پس تلاش دوباره پس از یک timeout بهجای فرستادن دوباره، همان نتیجهی اول را با Idempotency-Replayed: true برمیگرداند. ارسالی که با کلید انجام شود وقتی تهنشین شد 200 پاسخ میدهد و تا وقتی در صف یا زمانبندیشده است 202.
- کلیدها در تنظیمات ← کلیدهای API ساخته، محدود به scope، چرخانده و باطل میشوند. هر کلیدی که کنسول صادر میکند یک کلید oe_live_ است. پیشوند oe_test_ را هم راستیآزما میشناسد و هم مسیر ارسال، جایی که یک ارسال در حالت آزمایشی ثبت و بهعنوان فرستادهشده پاسخ داده میشود بیآنکه هرگز به هیچ ترابری برسد، اما هنوز هیچ چیزی نمیتواند یکی بسازد، و ارائهی این گزینه پیش از آنکه ترابریِ بیاثر بالای Durable Object بنشیند، کلید آزمایشیای به دستتان میداد که واقعاً تحویل میدهد. یک کلید یک scope ارسال تا 25 دامنهی کامل و 50 آدرس تکی حمل میکند، که در آن یک دامنهی کامل آدرسهایی را که بعداً به آن اضافه میشوند هم پوشش میدهد، یک انقضای اختیاری بین 1 تا 3650 روز، و بهدلخواه یک نقش. نقش سقف است نه یک اجازهی دوم: GET /ping هم scopeهای روی کلید و هم scopeهایی را که نقش برایش باقی گذاشته برمیگرداند، پس یک 403 برای scopeای که کلید شما آشکارا نامش را برده علت دیدنی دارد. باطلکردن یک بهروزرسانی است نه یک حذف، پس به فراخوانی بعدی بهجای اینکه صرفاً در احراز هویت شکست بخورد، revoked_api_key گفته میشود. چرخاندن همهچیز کلید را جز رمزش نگه میدارد: شناسه، scopeها، scope ارسال و تاریخچهی درخواستها ادامه مییابند، رمز قدیمی همان لحظه که رمز تازه ساخته شد میمیرد، و کلیدی که keys:write دارد میتواند خودش را روی API بچرخاند. همان کنشهای فهرستکردن، چرخاندن، باطلکردن و فعالکردن روی سرور MCP هم هست، برای هرکسی که نقشش اجازهی مدیریت کلیدها را میدهد.
- آنچه واقعاً غایب است: این API نقطهی پایانی بارگذاری از آنِ خودش ندارد. پیوستهای درونخطی بهصورت base64 و زیر سقف مجموع 5 MB میروند، و فایل بزرگتر با نامبردن فایلی که از پیش با شناسهاش در فضای کاری هست فرستاده میشود، که بهصورت یک لینک دانلود سفر میکند. برگشتخوردهها در صندوق پستی رسیدگی میشوند نه در گزارش ارسال: گزارش تحویل تجزیه میشود، با Message-ID به پیام اصلی متصل میشود، روی رشته برچسب میخورد و بهعنوان وبهوک email.bounced فرستاده میشود، اما چیزی به ردیف ارسال بازنویسی نمیکند، و وضعیت آن ردیف حالت bounced ندارد، پس از دید GET /emails یک پیام برگشتخورده همچنان sent خوانده میشود. نامهای که از بخش نگارشِ خودِ برنامه فرستاده شود هم در GET /emails ظاهر نمیشود، چون بخش نگارش از همان مسیر ارسال نمینویسد.