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

مهاجرت از Postmark به Mail.Land

Q: آیا Mail.Land از cc و bcc پشتیبانی میکند؟

نه در فراخوانی ارسال. هر گیرنده نسخهای جداگانه دریافت میکند، پس هر جا cc یا bcc به کار میبردید پیامی جداگانه بفرستید.

Q: آیا SDK رسمی برای Mail.Land وجود دارد؟

هنوز نه. مستندات نمونهکدهای آماده REST API را برای cURL، Node.js، Python، PHP، C#، Java و Go دارد و هر کتابخانه SMTP با رله کار میکند.

Postmark و Mail.Land هر دو فراخوانی ارسال را با JSON می‌پذیرند، پس بیشتر فیلدها یک‌به‌یک نگاشت می‌شوند. این راهنما هر فیلد رایج، تنظیمات لازم برای SMTP و تفاوت‌هایی را که به تغییر کد نیاز دارند فهرست می‌کند.

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

SMTP

# Before (Postmark)
SMTP_HOST=smtp.postmarkapp.com   # broadcasts: smtp-broadcasts.postmarkapp.com
SMTP_PORT=587                    # STARTTLS
SMTP_USER=<Server API token, or SMTP token access key>
SMTP_PASS=<Server API token, or SMTP token secret key>

# After (Mail.Land)
SMTP_HOST=smtp.mail.land
SMTP_PORT=587          # STARTTLS
SMTP_USER=apikey       # any value; Mail.Land ignores it
SMTP_PASS=ml_pet_...   # transactional; use an ml_pem_ key for broadcasts

مفاهیم Postmark در Mail.Land

مفاهیم Postmark در Mail.Land
Postmark	Mail.Land
Server و Server API token	فضای کاری و کلیدهای API (اعتبارنامه‌ها)، که هر کدام به API یا SMTP، به دامنه‌ها و به نشانی‌های IP محدود می‌شوند
جریان‌های پیام (تراکنشی، انبوه)	جریان کلید: تراکنشی (ml_pet_) یا بازاریابی (ml_pem_)
امضاهای فرستنده و دامنه‌ها	دامنه تأییدشده (SPF، DKIM، DMARC و مسیر بازگشت)
قالب‌ها و layoutها (Mustachio)	قالب‌هایی با جای‌نگهدارهای {{name}}
فهرست عدم ارسال برای هر جریان پیام	فهرست عدم ارسال با نوع و دامنه شمول
وب‌هوک‌ها	وب‌هوک‌های امضاشده با HMAC-SHA256، با یک کلید مخفی برای هر وب‌هوک
جریان ورودی	مسیرهای ورودی

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

در Postmark فیلد یا سرآیند MessageStream جریان را تعیین می‌کند. در Mail.Land این کار با کلید است: پیشوند آن حالت و جریان را نشان می‌دهد. برای هر برنامه و هر جریان یک کلید بسازید.

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

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

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

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

Postmark از Server API token یا SMTP token و یک سرآیند برای انتخاب جریان استفاده می‌کند. Mail.Land کلید API شما را به‌عنوان گذرواژه به کار می‌برد، نام کاربری را نادیده می‌گیرد و جریان را از کلید می‌گیرد.

تغییر SMTP: میزبان و اعتبارنامه‌ها را عوض کنید
تنظیم	Postmark	Mail.Land
میزبان	smtp.postmarkapp.com، یا smtp-broadcasts.postmarkapp.com برای ارسال انبوه	smtp.mail.land
درگاه	25، 587 یا 2525، با STARTTLS	587 با STARTTLS
نام کاربری	Server API token، یا access key مربوط به SMTP token	هر مقداری، برای نمونه apikey
گذرواژه	Server API token، یا secret key مربوط به SMTP token	یک کلید API از Mail.Land با SMTP فعال
جریان	سرآیند X-PM-Message-Stream	کلید: ml_pet_ برای تراکنشی، ml_pem_ برای بازاریابی

Mail.Land ورود را فقط پس از STARTTLS می‌پذیرد. Mail.Land به سرآیند X-PM-Message-Stream عمل نمی‌کند: کلید، جریان را تعیین می‌کند. اندازه هر پیام می‌تواند تا ۱۵ مبی‌بایت باشد.

مستندات رله SMTP

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

هر دو API با JSON کار می‌کنند. Postmark نام‌های PascalCase و سرآیند X-Postmark-Server-Token دارد؛ Mail.Land نام‌های camelCase و سرآیند X-API-Key. در اینجا یک پیام یکسان را در هر دو و یک ارسال با قالب را می‌بینید.

curl -X POST https://api.postmarkapp.com/email \
  -H "X-Postmark-Server-Token: $POSTMARK_SERVER_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "From": "Your Shop <[email protected]>",
    "To": "[email protected]",
    "ReplyTo": "[email protected]",
    "Subject": "Order 12345 has shipped",
    "TextBody": "Your order is on its way.",
    "HtmlBody": "<p>Your order is on its way.</p>",
    "Tag": "order-shipped",
    "MessageStream": "outbound"
  }'

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)

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

از POST /email و /email/withTemplate به POST /v1/transactional/send.

نگاشت فیلدهای فراخوانی ارسال
Postmark	Mail.Land	توضیح
`X-Postmark-Server-Token: <token>`	`X-API-Key: <key>`	سرآیندی دیگر.
`From`	`from.email, from.name`	نام نمایشی را از نشانی جدا کنید. نشانی باید روی دامنه‌ای تأییدشده باشد.
`To`	`to[].email, to[].name`	آرایه‌ای از شیءها به‌جای رشته‌ای جداشده با ویرگول. حداکثر ۵ گیرنده در هر درخواست با کلید تراکنشی؛ هر گیرنده نسخه‌ای جداگانه دریافت می‌کند.
`Cc, Bcc`	`ندارد`	پشتیبانی نمی‌شود. برای هر گیرنده پیامی جداگانه بفرستید.
`Subject`	`subject`	الزامی است، مگر اینکه از قالب استفاده کنید.
`HtmlBody`	`htmlContent`
`TextBody`	`textContent`
`ReplyTo`	`replyTo`	یک رشته نشانی واحد. اگر چند نشانی reply-to جداشده با ویرگول داشتید، یکی را نگه دارید.
`Tag`	`tags`	یک آرایه، بنابراین هر پیام می‌تواند چند برچسب داشته باشد.
`Metadata`	`ندارد`	فیلد فراداده کلید و مقدار وجود ندارد. از tags یا یک سرآیند سفارشی استفاده کنید.
`Headers [{ Name, Value }]`	`customHeaders`	شیئی از نام‌ها و مقدارهای سرآیند به‌جای آرایه.
`TrackOpens`	`tracking.opens`	انتخاب خود دامنه برای ردیابی باز شدن اولویت دارد.
`TrackLinks`	`tracking.clicks`	یک مقدار بولی به‌جای None، HtmlAndText، HtmlOnly یا TextOnly.
`Attachments[].Name, Content, ContentType, ContentID`	`attachments[].fileName, content, contentType, contentId, inline`	محتوای Base64 مانند قبل. برای تصویر درون‌خطی inline: true را تنظیم کنید. حداکثر ۱۰ پیوست و در مجموع ۱۰ مبی‌بایت.
`MessageStream`	`ندارد`	کلید جریان را تعیین می‌کند: ml_pet_ یا ml_pem_.
`TemplateId, TemplateAlias`	`templateId`	ابتدا قالب را در Mail.Land از نو بسازید؛ شناسه تازه‌ای می‌گیرد.
`TemplateModel`	`variables, to[].variables`	فقط مقدارهای ساده، زیرا جای‌نگهدارها بخش یا حلقه ندارند.
`POST /email/batch (حداکثر ۵۰۰ پیام)`	`POST /v1/transactional/send-batch`	مدلی دیگر: محتوای مشترک برای حداکثر ۱۰٬۰۰۰ گیرنده، هر کدام با متغیرهای خود، که با کلید بازاریابی فرستاده می‌شود. برای پیام‌های متفاوت، برای هر کدام یک فراخوانی ارسال جداگانه انجام دهید.
`معادلی ندارد`	`scheduledAt`	پیام را تا ۷ روز جلوتر زمان‌بندی کنید.
`معادلی ندارد`	`سرآیند X-Idempotency-Key`	در بازه نگهداری، تکرار درخواست با همان کلید پاسخ اصلی را برمی‌گرداند و دوباره ارسال نمی‌کند.

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

مستندات REST API

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

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

دامنه و رکوردهای 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 Postmark قرار می‌گیرد.
DMARC (TXT)	`_dmarc.yourdomain.com`	`v=DMARC1; p=...`	الزامی است. فقط یک رکورد DMARC نگه دارید؛ رکورد موجودی که سیاست داشته باشد کافی است.
مسیر بازگشت (CNAME)	`bounce.yourdomain.com`	`bounce.mlnd.net`	آن را روی DNS only و بدون پراکسی تنظیم کنید. بررسی کنید این نام از قبل استفاده نشده باشد.

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

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

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

Postmark فهرست عدم ارسال را برای هر جریان پیام جداگانه نگه می‌دارد. فهرست هر جریان را خروجی بگیرید، برای نمونه با GET /message-streams/<stream>/suppressions/dump، سپس آن را با نوع و دامنه شمول متناظر، در داشبورد یا با POST /v1/transactional/suppressions/import، به Mail.Land وارد کنید.

ابتدا فهرست‌های عدم ارسال را وارد کنید
دلیل در Postmark	نوع در Mail.Land	دامنه شمول
HardBounce	`HardBounce`	Global
SpamComplaint	`Complaint`	Global
ManualSuppression در جریان انبوه (لغو اشتراک‌ها)	`Unsubscribe`	Marketing؛ یا List، که فقط برای کارزارهای ارسال‌شده به فهرست پستی متناظر در Mail.Land اعمال می‌شود
ManualSuppression در جریان تراکنشی	`Manual`	Transactional

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

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

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

نقطه پایانی خود را در Mail.Land بیفزایید، رویدادها را انتخاب کنید و سرآیند X-MLND-Signature را با کلید مخفی همان وب‌هوک بررسی کنید. اگر نقطه پایانی Postmark خود را با احراز هویت Basic یا فهرست مجاز IP محافظت می‌کردید، به‌جای آن امضا را بررسی کنید.

وب‌هوک‌های خود را به Mail.Land هدایت کنید
وب‌هوک Postmark	رویداد Mail.Land	توضیح
`تحویل (Delivery)`	`message.delivered`
`برگشت (Bounce)`	`message.bounced`	برگشت‌های دائمی و موقت را پوشش می‌دهد. تأخیرهای موقت message.deferred هستند.
`شکایت هرزنامه (Spam complaint)`	`message.complained`
`تغییر اشتراک (Subscription change)`	`message.unsubscribed`	برای لغو اشتراک خود گیرنده فرستاده می‌شود، نه برای تغییراتی که شما از طریق API انجام می‌دهید.
`باز شدن، کلیک (Open, Click)`	`هنوز در دسترس نیست`	رویدادهای باز شدن و کلیک در فهرست رویدادها آمده‌اند اما امروز فرستاده نمی‌شوند.
`ورودی (Inbound)`	`inbound.received`	برای نشانی دریافت‌کننده یک مسیر ورودی تعریف کنید.
`خطای SMTP API`	`ندارد`	رله SMTP پیام را در همان جلسه، با یک کد پاسخ، رد می‌کند.

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

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

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

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

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

قالب‌های خود را از نو بسازید
Postmark	Mail.Land
`{{firstName}}`	`{{firstName}}`
`{{#each items}} ... {{/each}}`	`ندارد`
`{{#section}}, {{^section}}`	`ندارد`
`قالب‌های layout`	`ندارد`

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

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

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

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

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

منابع

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

[۱]Postmark Email APIhttps://postmarkapp.com/developer/api/email-apiبررسی‌شده در ۱۳ آبان ۱۴۰۵
[۲]Postmark Templates APIhttps://postmarkapp.com/developer/api/templates-apiبررسی‌شده در ۱۳ آبان ۱۴۰۵
[۳]Postmark: ارسال ایمیل با SMTPhttps://postmarkapp.com/developer/user-guide/send-email-with-smtpبررسی‌شده در ۱۳ آبان ۱۴۰۵
[۴]نمای کلی وب‌هوک‌های Postmarkhttps://postmarkapp.com/developer/webhooks/webhooks-overviewبررسی‌شده در ۱۳ آبان ۱۴۰۵
[۵]Postmark Suppressions APIhttps://postmarkapp.com/developer/api/suppressions-apiبررسی‌شده در ۱۳ آبان ۱۴۰۵

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

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

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

آیا Mail.Land از cc و bcc پشتیبانی می‌کند؟

نه در فراخوانی ارسال. هر گیرنده نسخه‌ای جداگانه دریافت می‌کند، پس هر جا cc یا bcc به کار می‌بردید پیامی جداگانه بفرستید.

جریان ارسال انبوه خود را چگونه جایگزین کنم؟

برای ارسال از طریق API از کلید بازاریابی (ml_pem_) با send-batch استفاده کنید، یا در طرح Pro یا Max یک کارزار در داشبورد بسازید.

آیا SDK رسمی برای Mail.Land وجود دارد؟

هنوز نه. مستندات نمونه‌کدهای آماده REST API را برای cURL، Node.js، Python، PHP، C#، Java و Go دارد و هر کتابخانه SMTP با رله کار می‌کند.

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

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

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