انتقال از SendGrid
SDK مربوط به SendGrid را نگه دارید و از طریق OpenEmail بفرستید. نشانی پایهٔ URL و کلید آن را عوض کنید، و کد ارسال شما همان‌طور که هست می‌ماند.
چه چیزی را عوض کنید
SDK را به https://api.openemail.uk/compat/sendgrid هدایت کنید و به‌جای کلید SendGrid یک کلید API از OpenEmail با مجوز emails:send به آن بدهید. کلید در همان سرآیند Authorization: Bearer فرستاده می‌شود. فراخوانی‌هایی که نامه می‌فرستند همان‌طور که هستند می‌مانند، و نشانی From تعیین می‌کند که پیام می‌تواند برود یا نه، مثل همه‌جای OpenEmail.
import sgMail from '@sendgrid/mail'import client from '@sendgrid/client' client.setApiKey(process.env.OPENEMAIL_API_KEY)client.setDefaultRequest('baseUrl', 'https://api.openemail.uk/compat/sendgrid')sgMail.setClient(client) await sgMail.send({ from: '[email protected]', to: '[email protected]', subject: 'Your invoice', html: '<p>Your invoice is attached.</p>',})در Node، اول کلید را روی کلاینت تنظیم کنید، بعد نشانی پایه را، و سپس کلاینت را به بستهٔ mail بدهید. بعد از آن sgMail.setApiKey را صدا نزنید، چون نشانی پایه را به SendGrid برمی‌گرداند. SDK هشدار می‌دهد که کلید با SG. شروع نمی‌شود، که بی‌ضرر است. در Python، Ruby و PHP، میزبان را بدون خط مورب پایانی بدهید.
چه چیزی به چه چیزی نگاشت می‌شود
نقطهٔ پایانی‌ای که پاسخ داده می‌شود POST /v3/mail/send است. هر مورد در personalizations به پیام جداگانه‌ای در OpenEmail با شناسهٔ خودش تبدیل می‌شود، پس هر درخواست حداکثر 100 پیام می‌فرستد.
| SendGrid | در OpenEmail |
|---|---|
| from | فرستنده، همراه با نامش. هر شخصی‌سازی می‌تواند from خودش را بدهد. |
| personalizations | هر کدام یک پیام. to، cc و bcc آن روی هم تا 50 گیرنده را جا می‌دهند، و subject، headers، custom_args، send_at و substitutions آن فقط روی همان پیام اعمال می‌شوند. |
| subject | موضوع، مگر اینکه شخصی‌سازی موضوع خودش را بگذارد. |
| content | text/plain بدنهٔ متنی و text/html بدنهٔ HTML می‌شود. text/x-amp-html کنار گذاشته می‌شود، چون بدنهٔ HTML خودش پیام را می‌رساند. |
| attachments | فایل‌ها، حداکثر 20 عدد و روی هم 5 مگابایت. تصویر درون‌خطی‌ای که HTML شناسهٔ content_id آن را به‌صورت cid: به کار می‌برد، در همان جایی که آمده جاسازی می‌شود. هر فایل درون‌خطی دیگر به‌صورت پیوست معمولی می‌رسد. |
| reply_to | نشانی پاسخ. reply_to_list هم تا وقتی فقط یک نشانی دارد کار می‌کند. |
| headers | سرآیندهای سفارشی: X-*، List-*، Reply-To، Precedence، Auto-Submitted، Importance، Priority و Feedback-ID. هر شخصی‌سازی سرآیندهای خودش را اضافه می‌کند. |
| categories | برچسب‌هایی با نام‌های category، category_2 و به همین ترتیب، که هر کدام یک دسته را نگه می‌دارد. |
| custom_args | برچسب‌هایی با همان نام‌ها و مقدارها. مقدارهای شخصی‌سازی اولویت دارند. |
| send_at | ارسال زمان‌بندی‌شده، تا یک سال جلوتر. زمانی که گذشته باشد فوراً می‌فرستد. |
| substitutions | هر کلید در موضوع، بدنهٔ متنی و بدنهٔ HTML همان پیام با مقدارش جایگزین می‌شود. |
| template_id | شناسه (tpl_...) یا slug یک قالب OpenEmail، که با dynamic_template_data پر می‌شود. |
| tracking_settings | open_tracking.enable و click_tracking.enable ردیابی باز شدن و کلیک را برای پیام روشن یا خاموش می‌کنند. |
| mail_settings | sandbox_mode.enable درخواست، فرستنده و قالب را بررسی می‌کند و بعد بدون فرستادن چیزی با 200 پاسخ می‌دهد. |
هر پیام حداکثر 10 برچسب دارد، با شمردن دسته‌ها و custom_args روی هم. درخواستی که بیشتر لازم دارد به‌جای کوتاه شدن رد می‌شود، تا چیزی از آنچه فرستاده‌اید بی‌صدا گم نشود.
چه چیزی رد می‌شود و چرا
- شناسهٔ قالب SendGrid در
template_id، مثلd-…. قالب‌ها در SendGrid می‌مانند، پس قالب را در OpenEmail دوباره بسازید و شناسه یا slug آن را بفرستید. contentدر کنارtemplate_id، چون قالب OpenEmail کل بدنه را فراهم می‌کند.substitutionsهمراه با قالب هم به همین دلیل: مقدارها را درdynamic_template_dataبفرستید.- بیش از یک نشانی پاسخ،
reply_toوreply_to_listبا هم، و انواع محتوایی غیر از متن و HTML. دعوت‌نامهٔ تقویم را به‌صورت پیوست.icsبفرستید. - روشن بودن
mail_settings.footer، وsections، چون OpenEmail متنی در پیام شما نمی‌نویسد. - بیش از 10 برچسب، نام برچسبی که چیزی جز حرف، رقم،
_و-داشته باشد، سرآیندی بیرون از فهرست بالا، و بیش از 100 شخصی‌سازی در یک درخواست.
asm، batch_id، ip_pool_name، تنظیمات دور زدن در mail_settings، subscription_tracking، ganalytics، click_tracking.enable_text و open_tracking.substitution_tag پذیرفته می‌شوند و چیزی را تغییر نمی‌دهند. نشانی‌های فهرست توقیف فضای کاری همیشه نادیده گرفته می‌شوند، هر چه یک تنظیم دور زدن بگوید.
پاسخ‌ها و خطاها
- هر ارسال با 202، بدنهٔ خالی و شناسهٔ پیام OpenEmail در
X-Message-Idپاسخ می‌دهد، همان شناسه‌ای کهGET /emails/{id}و وب‌هوک‌ها به کار می‌برند. با چند شخصی‌سازی، شناسهٔ پیام اول در آن است. سرآیندIdempotency-Keyمثل بقیهٔ API کار می‌کند. - خطاها به‌صورت
errorsبرمی‌گردند، فهرستی ازmessage،fieldوhelp: 400 برای درخواستی که نمی‌شود فرستاد، 401 برای کلید ناموجود یا ناشناخته، 403 برای کلیدی بدونemails:sendیا نشانی From که کلید اجازهٔ استفاده از آن را ندارد یا دامنه‌اش هنوز نمی‌تواند بفرستد، 413 برای بدنهٔ بیشتر از 30 مگابایت یا پیوست‌های بیشتر از 5 مگابایت، و 429 وقتی فضای کاری سهمیهٔ ارسالش را تمام کرده باشد. - اگر یک شخصی‌سازی بعد از پذیرفته شدن قبلی‌ها شکست بخورد، خطا پیام‌هایی را که فرستاده شده‌اند نام می‌برد، تا تلاش دوباره بتواند آن‌ها را کنار بگذارد.