راهنمای مهاجرت

مهاجرت از Amazon SES به Mail.Land

Q: آیا هنوز به SDK AWS نیاز دارم؟

خیر. هر کلاینت HTTP میتواند API Mail.Land را با سرآیند X-API-Key فراخوانی کند و هر کتابخانه SMTP با رله کار میکند.

Q: Mail.Land کجا اجرا میشود؟

Mail.Land منطقهای برای انتخاب ندارد. نسخه اصلی دادههای شما در آلمان است؛ ارائهدهندگان بیرون از اتحادیه اروپا در صفحه GDPR ما فهرست شدهاند.

انتقال از SES، اعتبارنامه‌های AWS، مجموعه‌های پیکربندی و مقصدهای رویداد را با یک کلید API و وب‌هوک‌های امضاشده جایگزین می‌کند. این راهنما هر فیلد رایج SendEmail را نگاشت می‌کند و مواردی را که به تغییر کد نیاز دارند فهرست می‌کند.

رایگان شروع کنید درخواست کمک برای مهاجرت

SMTP

# Before (Amazon SES)
SMTP_HOST=email-smtp.eu-central-1.amazonaws.com   # your Region's endpoint
SMTP_PORT=587          # STARTTLS (465 for TLS wrapper)
SMTP_USER=<SES SMTP user name for that Region>
SMTP_PASS=<SES SMTP password for that Region>

# After (Mail.Land)
SMTP_HOST=smtp.mail.land
SMTP_PORT=587          # STARTTLS; 465 is not offered
SMTP_USER=apikey       # any value; Mail.Land ignores it
SMTP_PASS=ml_pet_...   # a Mail.Land key with SMTP enabled

مفاهیم Amazon SES در Mail.Land

مفاهیم Amazon SES در Mail.Land
Amazon SES	Mail.Land
کاربر IAM و امضای درخواست SigV4	کلید API (اعتبارنامه) در سرآیند X-API-Key
اعتبارنامه‌های SMTP برای هر منطقه AWS	همان کلید API، که به‌عنوان گذرواژه SMTP به کار می‌رود
هویت تأییدشده (دامنه) و MAIL FROM سفارشی	دامنه تأییدشده (SPF، DKIM، DMARC و مسیر بازگشت)
مجموعه‌های پیکربندی و مقصدهای رویداد (SNS، EventBridge، Firehose)	وب‌هوک‌های امضاشده با HMAC-SHA256 که مستقیم به نقطه پایانی شما فرستاده می‌شوند
فهرست عدم ارسال در سطح حساب	فهرست عدم ارسال با نوع و دامنه شمول
قالب‌های ایمیل (Handlebars)	قالب‌هایی با جای‌نگهدارهای {{name}}
فهرست‌های مخاطب و موضوع‌ها (topics)	فهرست‌های پستی، کارزارها و مدیریت لغو اشتراک (Pro و Max)
محیط آزمایشی (Sandbox)	کلیدهای آزمایشی (ml_set_، ml_sem_): با sandboxBehavior برابر LogOnly، درخواست‌ها پذیرفته و ثبت می‌شوند اما هرگز تحویل داده نمی‌شوند

کلیدهای API مناسب را بسازید

نیازی به نوشتن سیاست IAM نیست. پیشوند هر کلید Mail.Land حالت و جریان آن را نشان می‌دهد؛ برای هر برنامه و هر جریان یک کلید بسازید و آن را به دامنه‌ها و نشانی‌های IP که از آن استفاده می‌کنند محدود کنید.

کلیدهای API مناسب را بسازید
پیشوند	کاربرد
`ml_pet_`	تولیدی، تراکنشی: رسیدها، بازنشانی گذرواژه، هشدارها. حداکثر ۵ گیرنده در هر درخواست.
`ml_pem_`	تولیدی، بازاریابی: خبرنامه‌ها و ارسال انبوه با send-batch، حداکثر ۱۰٬۰۰۰ گیرنده در هر فراخوانی.
`ml_set_`	آزمایشی، تراکنشی: با sandboxBehavior برابر LogOnly (پیش‌فرض)، درخواست‌ها پذیرفته و ثبت می‌شوند اما هرگز تحویل داده نمی‌شوند. از آن برای آزمون‌های یکپارچه‌سازی استفاده کنید.

هر کلید را می‌توان به API، به SMTP یا هر دو، به دامنه‌های انتخابی و به نشانی‌های IP شناخته‌شده محدود کرد. هر کلید فقط یک بار نمایش داده می‌شود و Mail.Land تنها درهم‌سازی (hash) آن را نگه می‌دارد.

مستندات کلیدهای API

تغییر SMTP: میزبان و اعتبارنامه‌ها را عوض کنید

اعتبارنامه‌های SMTP در SES از طریق IAM ساخته می‌شوند و در هر منطقه AWS متفاوت‌اند. Mail.Land کلید API شما را به‌عنوان گذرواژه به کار می‌برد و نام کاربری را نادیده می‌گیرد.

تغییر SMTP: میزبان و اعتبارنامه‌ها را عوض کنید
تنظیم	Amazon SES	Mail.Land
میزبان	email-smtp.<region>.amazonaws.com	smtp.mail.land
درگاه	25، 587 یا 2587 با STARTTLS، یا 465 و 2465 با TLS wrapper	587 با STARTTLS
نام کاربری	نام کاربری SMTP برای همان منطقه	هر مقداری، برای نمونه apikey
گذرواژه	گذرواژه SMTP برای همان منطقه	یک کلید API از Mail.Land با SMTP فعال (ml_pet_ برای ایمیل تراکنشی)

Mail.Land ورود را فقط پس از STARTTLS می‌پذیرد و درگاه‌های 465 و 2465 ارائه نمی‌شوند. اگر برنامه شما از TLS wrapper استفاده می‌کند، آن را به 587 با STARTTLS تغییر دهید. Mail.Land به سرآیندهای X-SES-* مانند X-SES-CONFIGURATION-SET عمل نمی‌کند، پس می‌توانید آن‌ها را حذف کنید. اندازه هر پیام می‌تواند تا ۱۵ مبی‌بایت باشد.

مستندات رله SMTP

تغییر فراخوانی API

درخواست‌های SES با AWS Signature Version 4 امضا می‌شوند، معمولاً از طریق یک SDK AWS. Mail.Land فقط به سرآیند X-API-Key و بدنه JSON ساده‌تری نیاز دارد. در اینجا یک پیام یکسان را در هر دو و یک ارسال با قالب را می‌بینید.

aws sesv2 send-email --region eu-central-1 \
  --from-email-address "[email protected]" \
  --destination '{"ToAddresses":["[email protected]"]}' \
  --reply-to-addresses "[email protected]" \
  --email-tags Name=type,Value=order-shipped \
  --content '{
    "Simple": {
      "Subject": { "Data": "Order 12345 has shipped" },
      "Body": {
        "Text": { "Data": "Your order is on its way." },
        "Html": { "Data": "<p>Your order is on its way.</p>" }
      }
    }
  }'

curl -X POST https://api.mail.land/v1/transactional/send \
  -H "X-API-Key: $MAILLAND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": { "email": "[email protected]", "name": "Your Shop" },
    "to": [{
      "email": "[email protected]", "name": "Jane",
      "variables": { "orderNumber": "12345" }
    }],
    "replyTo": "[email protected]",
    "subject": "Order {{orderNumber}} has shipped",
    "textContent": "Your order {{orderNumber}} is on its way.",
    "htmlContent": "<p>Your order {{orderNumber}} is on its way.</p>",
    "tags": ["order-shipped"]
  }'
# MAILLAND_API_KEY=ml_pet_...  (production, transactional)

نگاشت فیلدهای فراخوانی ارسال

از SES API v2 SendEmail (POST /v2/email/outbound-emails) به POST /v1/transactional/send.

نگاشت فیلدهای فراخوانی ارسال
Amazon SES	Mail.Land	توضیح
`AWS Signature Version 4`	`X-API-Key: <key>`	بدون امضای درخواست؛ کلید را از طریق HTTPS بفرستید.
`FromEmailAddress`	`from.email, from.name`	نشانی باید روی دامنه‌ای تأییدشده باشد.
`Destination.ToAddresses`	`to[].email, to[].name`	حداکثر ۵ گیرنده در هر درخواست با کلید تراکنشی؛ هر گیرنده نسخه‌ای جداگانه دریافت می‌کند.
`Destination.CcAddresses, BccAddresses`	`ندارد`	پشتیبانی نمی‌شود. برای هر گیرنده پیامی جداگانه بفرستید.
`ReplyToAddresses`	`replyTo`	یک رشته نشانی واحد به‌جای فهرست. اگر چند نشانی داشتید، یکی را نگه دارید.
`Content.Simple.Subject.Data`	`subject`	الزامی است، مگر اینکه از قالب استفاده کنید.
`Content.Simple.Body.Html.Data`	`htmlContent`
`Content.Simple.Body.Text.Data`	`textContent`
`Content.Simple.Headers [{ Name, Value }]`	`customHeaders`	شیئی از نام‌ها و مقدارهای سرآیند به‌جای آرایه.
`Content.Simple.Attachments[].FileName, ContentType, RawContent, ContentId, ContentDisposition`	`attachments[].fileName, contentType, content, contentId, inline`	محتوای Base64. برای تصویر درون‌خطی inline: true را تنظیم کنید. حداکثر ۱۰ پیوست و در مجموع ۱۰ مبی‌بایت.
`Content.Raw.Data (MIME)`	`در API ندارد`	پیام‌های آماده MIME را به‌جای آن از طریق رله SMTP بفرستید.
`Content.Template.TemplateName, TemplateArn`	`templateId`	ابتدا قالب را در Mail.Land از نو بسازید.
`Content.Template.TemplateData`	`variables, to[].variables`	یک شیء JSON به‌جای رشته JSON.
`EmailTags [{ Name, Value }]`	`tags`	آرایه‌ای از رشته‌ها به‌جای جفت‌های نام و مقدار.
`ConfigurationSetName`	`ندارد`	وب‌هوک‌ها و ردیابی در حساب Mail.Land شما و روی هر دامنه تنظیم می‌شوند.
`ConfigurationOverrides.Tracking`	`tracking.opens, tracking.clicks`	انتخاب خود دامنه برای ردیابی باز شدن اولویت دارد.
`ListManagementOptions`	`در فراخوانی ارسال ندارد`	لغو اشتراک‌های بازاریابی را فهرست‌ها و کارزارهای Mail.Land مدیریت می‌کنند.
`معادلی ندارد`	`scheduledAt`	پیام را تا ۷ روز جلوتر زمان‌بندی کنید.
`معادلی ندارد`	`سرآیند X-Idempotency-Key`	در بازه نگهداری، تکرار درخواست با همان کلید پاسخ اصلی را برمی‌گرداند و دوباره ارسال نمی‌کند.

SES با ۲۰۰ و یک MessageId پاسخ می‌دهد. Mail.Land با 202 Accepted پاسخ می‌دهد، همراه با یک jobId، یک شناسه پیام برای هر گیرنده پذیرفته‌شده و فهرست گیرندگان پذیرفته‌شده و ردشده.

مستندات REST API

دامنه و رکوردهای DNS خود را بیفزایید

دامنه را در Mail.Land بیفزایید و رکوردهایی را که داشبورد نشان می‌دهد منتشر کنید. SPF، DKIM و DMARC باید پیش از ارسال تأیید شوند. می‌توانید این کار را در حالی انجام دهید که SES هنوز ارسال می‌کند.

دامنه و رکوردهای DNS خود را بیفزایید
رکورد	نام	مقدار	توضیح
SPF (TXT)	`yourdomain.com`	`include:spf.mlnd.net`	include را به رکورد SPF فعلی خود بیفزایید. هر دامنه باید فقط یک رکورد SPF داشته باشد.
DKIM (TXT)	`mlnd._domainkey.yourdomain.com`	`v=DKIM1; k=rsa; p=...`	انتخابگر (selector) برابر mlnd است، بنابراین این رکورد در کنار رکوردهای DKIM که SES به کار می‌برد قرار می‌گیرد.
DMARC (TXT)	`_dmarc.yourdomain.com`	`v=DMARC1; p=...`	الزامی است. فقط یک رکورد DMARC نگه دارید؛ رکورد موجودی که سیاست داشته باشد کافی است.
مسیر بازگشت (CNAME)	`bounce.yourdomain.com`	`bounce.mlnd.net`	آن را روی DNS only و بدون پراکسی تنظیم کنید. اگر دامنه MAIL FROM سفارشی شما در SES از قبل از این نام استفاده می‌کند، آن را تا توقف ارسال SES نگه دارید.

رکوردهای DNS SES را تا پایان انتقال نگه دارید و فقط پس از رفتن آخرین پیام آن حذفشان کنید.

مستندات راه‌اندازی DNS

ابتدا فهرست عدم ارسال را وارد کنید

فهرست عدم ارسال سطح حساب در SES برای هر منطقه AWS جداگانه است. آن را از هر منطقه‌ای که از آن می‌فرستید با ListSuppressedDestinations (aws sesv2 list-suppressed-destinations) خروجی بگیرید، سپس با نوع و دامنه شمول متناظر، در داشبورد یا با POST /v1/transactional/suppressions/import، به Mail.Land وارد کنید.

ابتدا فهرست عدم ارسال را وارد کنید
دلیل یا منبع در SES	نوع در Mail.Land	دامنه شمول
BOUNCE	`HardBounce`	Global
COMPLAINT	`Complaint`	Global
لغو اشتراک از موضوع فهرست مخاطب	`Unsubscribe`	Marketing؛ یا List، که فقط برای کارزارهای ارسال‌شده به فهرست پستی متناظر در Mail.Land اعمال می‌شود

SES فقط برگشتی‌های دائمی را به این فهرست می‌افزاید و گزارش‌های هرزنامه Gmail به آن نمی‌رسند، پس هر فهرست عدم ارسالی را که سامانه‌های خودتان نگه می‌دارند هم وارد کنید. پیش از نخستین ارسال از طریق Mail.Land وارد کنید تا کسانی که انصراف داده‌اند از همان ابتدا در فهرست عدم ارسال بمانند.

مستندات فهرست عدم ارسال

وب‌هوک‌های خود را به Mail.Land هدایت کنید

مجموعه پیکربندی و مقصد رویداد آن را با یک وب‌هوک Mail.Land جایگزین کنید: نقطه پایانی HTTPS خود را بیفزایید، رویدادها را انتخاب کنید و سرآیند X-MLND-Signature را با کلید مخفی همان وب‌هوک بررسی کنید. اشتراک SNS برای تأیید وجود ندارد.

وب‌هوک‌های خود را به Mail.Land هدایت کنید
رویداد SES	رویداد Mail.Land	توضیح
`Send`	`فعلاً ندارد`	message.sent هنوز در دسترس نیست؛ پاسخ 202 پذیرش را تأیید می‌کند.
`تحویل (Delivery)`	`message.delivered`
`DeliveryDelay`	`message.deferred`
`برگشت (Bounce)`	`message.bounced`
`Complaint`	`message.complained`
`Subscription`	`message.unsubscribed`	برای لغو اشتراک خود گیرنده فرستاده می‌شود، نه برای تغییراتی که شما از طریق API انجام می‌دهید.
`Reject`	`ندارد`
`RenderingFailure`	`ندارد`	نبود یک مقدار قالب، هنگام فراخوانی API با 422 TEMPLATE_VARIABLE_MISSING رد می‌شود.
`باز شدن، کلیک (Open, Click)`	`هنوز در دسترس نیست`	رویدادهای باز شدن و کلیک در فهرست رویدادها آمده‌اند اما امروز فرستاده نمی‌شوند.

بر اساس event_id تکرارها را حذف کنید، زیرا تحویل دوباره همان شناسه رویداد را دارد. وضعیت ممکن است بعداً اصلاح شود، پس پس از رویداد نهایی هم پردازش رویدادها را ادامه دهید و status_version را مقایسه کنید.

رویدادهای وب‌هوک

بررسی امضای وب‌هوک

قالب‌های خود را از نو بسازید

هر قالب را در داشبورد Mail.Land یا با API قالب‌ها بسازید و سپس آن را با templateId و variables بفرستید. هر جای‌نگهدار باید مقداری داشته باشد، وگرنه ارسال با کد 422 و نام موارد ناموجود رد می‌شود.

قالب‌های خود را از نو بسازید
Amazon SES	Mail.Land
`{{firstName}}`	`{{firstName}}`
`{{contact.firstName}} (تودرتو)`	`{{firstName}}`
`{{#each}}, {{#if}} ... {{else}}`	`ندارد`
`partialهای درون‌خطی ({{> name}})`	`ندارد`

جای‌نگهدارهای Mail.Land ساده‌اند: بدون مقدار تودرتو، شرط، حلقه یا partial. مقدارهای ساده بفرستید و منطق را به برنامه خود منتقل کنید، یا برای هر حالت یک قالب جداگانه نگه دارید.

مستندات قالب‌ها

انتقال گام‌به‌گام

دامنه ارسال خود را در Mail.Land بیفزایید و تأیید کنید و include:spf.mlnd.net را به رکورد SPF فعلی خود بیفزایید.
فهرست عدم ارسال هر منطقه AWS را که استفاده می‌کنید خروجی بگیرید و وارد کنید.
برای هر برنامه و هر جریان کلیدهای Mail.Land بسازید و آن‌ها را به دامنه‌ها و نشانی‌های IP خود محدود کنید.
قالب‌های خود را از نو بسازید و هر مقصد رویداد را با یک وب‌هوک جایگزین کنید.
یک کلید آزمایشی با sandboxBehavior برابر LogOnly بسازید و آزمون‌های یکپارچه‌سازی خود را بدون تحویل ایمیل روی Mail.Land اجرا کنید.
پیام‌های واقعی به نشانی‌هایی که در اختیار دارید بفرستید و آن‌ها را در گزارش ایمیل بررسی کنید.
یک برنامه یا سهم کوچکی از ترافیک را منتقل کنید و سپس تحویل، برگشتی‌ها و شکایت‌ها را زیر نظر بگیرید.
تا وقتی هر دو ارائه‌دهنده فعال‌اند، انصراف‌ها را در هر دو سو همگام نگه دارید: لغو اشتراک‌ها، شکایت‌ها و برگشتی‌های جدید را از SES به Mail.Land و از Mail.Land به SES کپی کنید و پیش از انتقال باقی ترافیک یک همگام‌سازی نهایی انجام دهید.
گرم‌کردن دامنه را بررسی کنید: در Free و Pro، دامنه تازه سقف روزانه‌ای دارد که مرحله‌به‌مرحله بالا می‌رود و ارسال‌های بیش از آن رد می‌شوند. انتقال را در همین حدود برنامه‌ریزی کنید یا درباره برنامه سفارشی از ما بپرسید. طرح Max مرحله گرم‌کردن ندارد.
سپس باقی ترافیک را منتقل کنید و SES را تا رفتن آخرین پیام‌های آن فعال نگه دارید.

Mail.Land در برابر Amazon SES: مقایسه مستند

منابع

صفحه‌های عمومی AWS که در این راهنما استفاده شده‌اند.

[۱]Amazon SES API v2: SendEmailhttps://docs.aws.amazon.com/ses/latest/APIReference-V2/API_SendEmail.htmlبررسی‌شده در ۱۳ آبان ۱۴۰۵
[۲]Amazon SES: اتصال به نقطه پایانی SMTPhttps://docs.aws.amazon.com/ses/latest/dg/smtp-connect.htmlبررسی‌شده در ۱۳ آبان ۱۴۰۵
[۳]Amazon SES: دریافت اعتبارنامه‌های SMTPhttps://docs.aws.amazon.com/ses/latest/dg/smtp-credentials.htmlبررسی‌شده در ۱۳ آبان ۱۴۰۵
[۴]Amazon SES: شخصی‌سازی پیشرفته ایمیلhttps://docs.aws.amazon.com/ses/latest/dg/send-personalized-email-advanced.htmlبررسی‌شده در ۱۳ آبان ۱۴۰۵
[۵]Amazon SES: انتشار رویدادهاhttps://docs.aws.amazon.com/ses/latest/dg/monitor-using-event-publishing.htmlبررسی‌شده در ۱۳ آبان ۱۴۰۵
[۶]Amazon SES: فهرست عدم ارسال سطح حسابhttps://docs.aws.amazon.com/ses/latest/dg/sending-email-suppression-list.htmlبررسی‌شده در ۱۳ آبان ۱۴۰۵

پرسش‌های متداول

آیا هنگام آزمایش می‌توانم همچنان از طریق SES ارسال کنم؟

بله. تأیید دامنه در Mail.Land جلوی ارسال SES برای آن دامنه را نمی‌گیرد، پس می‌توانید هر دو را اجرا کنید و ترافیک را به‌تدریج منتقل کنید.

آیا هنوز به SDK AWS نیاز دارم؟

خیر. هر کلاینت HTTP می‌تواند API Mail.Land را با سرآیند X-API-Key فراخوانی کند و هر کتابخانه SMTP با رله کار می‌کند.

ایمیل انبوهی را که با SendBulkEmail می‌فرستادم چگونه بفرستم؟

از POST /v1/transactional/send-batch با کلید بازاریابی (ml_pem_) استفاده کنید. این نقطه پایانی تا ۱۰٬۰۰۰ گیرنده را، هر کدام با متغیرهای خود، می‌پذیرد.

Mail.Land کجا اجرا می‌شود؟

Mail.Land منطقه‌ای برای انتخاب ندارد. نسخه اصلی داده‌های شما در آلمان است؛ ارائه‌دهندگان بیرون از اتحادیه اروپا در صفحه GDPR ما فهرست شده‌اند.

آماده انتقال از Amazon SES هستید؟

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

رایگان شروع کنید درخواست کمک برای مهاجرت