انتقال از Mailgun
SDK مربوط به Mailgun را نگه دارید و از طریق OpenEmail بفرستید. نشانی پایهٔ URL و کلید آن را عوض کنید، و کد ارسال شما همان‌طور که هست می‌ماند.
چه چیزی را عوض کنید
SDK را به https://api.openemail.uk/compat/mailgun هدایت کنید و به‌جای کلید Mailgun یک کلید API از OpenEmail با مجوز emails:send به آن بدهید. کلید به‌عنوان گذرواژهٔ همان ورود HTTP Basic فرستاده می‌شود و نام کاربری بررسی نمی‌شود. دامنهٔ داخل مسیر باید یکی از دامنه‌های فضای کاری باشد، و نشانی From تعیین می‌کند که پیام می‌تواند برود یا نه، مثل همه‌جای OpenEmail.
import formData from 'form-data'import Mailgun from 'mailgun.js' const mailgun = new Mailgun(formData)const mg = mailgun.client({ username: 'api', key: process.env.OPENEMAIL_API_KEY, url: 'https://api.openemail.uk/compat/mailgun',}) await mg.messages.create('acme.com', { from: 'Acme Billing <[email protected]>', to: ['[email protected]'], subject: 'Your invoice', html: '<p>Your invoice is attached.</p>',})در Ruby، آرگومان دوم میزبان و مسیر بدون طرح است. در PHP، SDK از نقطهٔ پایانی‌ای که به آن داده می‌شود فقط میزبان را نگه می‌دارد، پس مسیر از طریق AddPathPlugin از php-http اضافه می‌شود که SDK خودش آن را نصب می‌کند. بستهٔ رسمی Python ممکن است هشداری ثبت کند که میزبان مال Mailgun نیست، و با این حال می‌فرستد. همچنین درخواستی را که با 429 یا یک 5xx شکست خورده دوباره امتحان می‌کند، برای همین OpenEmail وقتی بخشی از یک دسته رفته باشد به‌جای 5xx با 400 پاسخ می‌دهد.
چه چیزی به چه چیزی نگاشت می‌شود
نقطهٔ پایانی‌ای که پاسخ داده می‌شود POST /v3/{domain}/messages است، به‌صورت multipart/form-data که پیوست‌ها به آن نیاز دارند، یا application/x-www-form-urlencoded. نام فیلدی که به [] ختم شود بدون آن خوانده می‌شود.
| Mailgun | در OpenEmail |
|---|---|
| from | فرستنده، همراه با نامش. |
| to | گیرنده‌ها، تکرارشده یا جداشده با ویرگول. همراه با cc و bcc، تا 50 برای هر پیام. |
| subject | موضوع. |
| html | بدنهٔ HTML. text بدنهٔ متنی می‌شود، و یکی از این دو، یا template، لازم است. |
| attachment | فایل‌ها، حداکثر 20 عدد و روی هم 5 مگابایت. |
| inline | تصویری که HTML آن را با نام فایلش به‌صورت cid: به کار می‌برد، در همان جایی که آمده جاسازی می‌شود. هر فایل درون‌خطی دیگر به‌صورت پیوست معمولی می‌رسد. |
| o:tag | برچسب‌هایی با نام‌های tag، tag_2 و به همین ترتیب، که هر کدام یک برچسب را نگه می‌دارد. |
| v: | هر متغیر با نام و مقدارش به یک برچسب تبدیل می‌شود. همراه با o:tag، حداکثر 10 برای هر پیام. |
| o:deliverytime | ارسال زمان‌بندی‌شده، تا یک سال جلوتر. زمانی که گذشته باشد فوراً می‌فرستد. |
| o:tracking | همراه با o:tracking-clicks و o:tracking-opens، ردیابی را برای پیام روشن یا خاموش می‌کند. htmlonly روشن به حساب می‌آید. |
| o:testmode | yes پیام را بدون تحویل دادن، فرستاده‌شده ثبت می‌کند، همان‌طور که یک کلید oe_test_ این کار را می‌کند. |
| h:Reply-To | نشانی پاسخ. هر فیلد h: دیگر به یک سرآیند سفارشی تبدیل می‌شود: X-*، List-*، Precedence، Auto-Submitted، Importance، Priority و Feedback-ID. |
| recipient-variables | ارسال دسته‌ای. هر نشانی در to پیام خودش را می‌گیرد، که در آن %recipient.key% از متغیرهایش و %recipient% با نشانی‌اش پر می‌شود، و cc و bcc روی هر کدام می‌آیند. جانگهداری که مقداری ندارد همان‌طور که هست می‌ماند. |
| template | slug یا شناسهٔ (tpl_...) یک قالب OpenEmail، که با t:variables و در غیر این صورت با h:X-Mailgun-Variables پر می‌شود. t:version نسخه‌ای را با شماره‌اش انتخاب می‌کند. |
چه چیزی رد می‌شود و چرا
templateهمراه باhtmlیاtext، چون قالب OpenEmail کل بدنه را فراهم می‌کند، وt:versionکه شمارهٔ نسخه نباشد.o:deliverytime-optimize-periodوo:time-zone-localize، چون OpenEmail برای هر گیرنده زمان ارسال جداگانه‌ای انتخاب نمی‌کند. سرآیندهای دیگرh:X-Mailgun-، که دستورهایی برای Mailgun هستند: به‌جای آن‌ها گزینهٔo:متناظر را به کار ببرید.amp-htmlبه‌تنهایی. در کنارhtmlیاtextکنار گذاشته می‌شود، چون آن‌ها خودشان پیام را می‌رسانند.- بیش از یک نشانی پاسخ، بیش از 10 برچسب، نام برچسبی که چیزی جز حرف، رقم،
_و-داشته باشد، و دسته‌ای با بیش از 100 گیرنده. Mailgun تا 1000 می‌پذیرد، پس دسته‌های بزرگ‌تر را تقسیم کنید.
o:dkim، o:require-tls، o:skip-verification، o:sending-ip، o:sending-ip-pool، o:tracking-pixel-location-top، o:archive-to، o:deliver-within و t:text پذیرفته می‌شوند و چیزی را تغییر نمی‌دهند.
پاسخ‌ها و خطاها
- هر ارسال با 200 همراه با پیام
Queued. Thank you.و یکidپاسخ می‌دهد: شناسهٔ پیام OpenEmail درون دو کروشهٔ زاویه‌ای، کهGET /emails/{id}و وب‌هوک‌ها آن را بدون آن‌ها به کار می‌برند. ارسال دسته‌ای برای هر گیرنده یک پیام می‌سازد، هر کدام با شناسهٔ خودش، و با اولی پاسخ می‌دهد. سرآیندIdempotency-Keyمثل بقیهٔ API کار می‌کند. - کلید ناموجود یا ناشناخته با 401 و متن سادهٔ
Forbiddenپاسخ می‌گیرد، و دامنه‌ای که فضای کاری ندارد با 404 وDomain not found. بقیهٔ موارد به‌صورت یکmessageبرمی‌گردند: 400 برای پیامی که نمی‌شود فرستاد، 403 برای کلیدی بدونemails:send، نشانی From که کلید اجازهٔ استفاده از آن را ندارد، دامنه‌ای که هنوز نمی‌تواند بفرستد یا فضای کاری‌ای که سهمیهٔ ارسالش را تمام کرده است، و 413 برای بدنهٔ بیشتر از 25 مگابایت یا پیوست‌های بیشتر از 5 مگابایت. - اگر یک گیرندهٔ دسته بعد از پذیرفته شدن دیگران شکست بخورد، خطا پیام‌هایی را که فرستاده شده‌اند نام می‌برد و با 400 پاسخ می‌دهد، تا یک SDK که درخواست‌ها را دوباره می‌فرستد آن‌ها را دو بار نفرستد.