مسیرهای ورودی

مسیرها تعیین می‌کنند که MailLand چگونه ایمیل‌های دریافتی یک دامنه را پردازش می‌کند. هر مسیر با بخش محلی گیرنده (بخشی از آدرس پیش از @) تطبیق داده می‌شود و یک یا چند اقدام را اجرا می‌کند: ذخیره‌سازی، تحویل به وب‌هوک، ارسال به جلو، رد در سطح SMTP، یا حذف. مسیرها به ترتیب اولویت (عدد کوچک‌تر ابتدا) ارزیابی می‌شوند و اولین مسیر تطبیق‌یافته برنده می‌شود.

انواع تطبیقکپی پیوند بخش

تطبیق به بزرگی و کوچکی حروف حساس نیست و همیشه روی بخش محلی انجام می‌شود: هر دوی [email protected] و [email protected] با مسیری با الگوی support که به همان دامنه محدود شده، تطبیق دارند.

اقدامات مسیرکپی پیوند بخش

فیلد actions یک مسیر، فهرستی از یک یا چند مقدار رشته‌ای زیر است:

store و webhook می‌توانند با یکدیگر و با forward ترکیب شوند. اما reject، drop و unsubscribe پایانی هستند: هر یک باید تنها اقدام مسیر باشد؛ API درخواستی را که یکی از این‌ها را با اقدام دیگری ترکیب کند، رد می‌کند.

مقصدهای فورواردکپی پیوند بخش

پیش از آنکه هیچ ایمیلی به یک آدرس فوروارد شود، مالک آن آدرس باید آن را تأیید کند: مگر اینکه آدرس روی یکی از دامنه‌های خودتان باشد که به‌طور کامل برای ارسال تأیید شده است. برای یک آدرس بیرونی راهی برای دور زدن این قاعده وجود ندارد: این کار مالک مقصد را از دریافت ایمیلی که هرگز به آن رضایت نداده محافظت می‌کند و اعتبار ارسال شما را در برابر آدرسی که برگشت می‌خورد یا شکایت می‌کند حفظ می‌کند.

هنگام ایجاد یا به‌روزرسانی مسیری با forward در actions، MailLand به‌طور خودکار:

۱. یک رکورد مقصد فوروارد برای forwardToEmail می‌سازد (یا از رکورد موجود استفاده می‌کند)، مختص مستأجر شما: همان آدرس در تمام مسیرهایی که به آن فوروارد می‌کنند به‌خاطر سپرده می‌شود.

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

ذخیرهٔ خود مسیر همیشه موفق می‌شود؛ شکست ایمیل تأیید باعث شکست ذخیرهٔ مسیر نمی‌شود: مقصد فقط pending باقی می‌ماند (چیزی به آن فوروارد نمی‌شود) تا زمانی که تأیید را دوباره ارسال کنید.

لینک تأییدکپی پیوند بخش

لینک درون ایمیل تأیید ۷ روز اعتبار دارد و یک‌بارمصرف است: به‌محض اینکه گیرنده تأیید یا رد کند، بازدید مجدد از لینک فقط همان تصمیم را نشان می‌دهد، با بازدید دوباره قابل بازگشت نیست. لینکی که منقضی شده و هرگز تصمیمی برایش گرفته نشده، در صورت باز شدن دوباره 410 Gone برمی‌گرداند.

• تأیید: از این پس ایمیل فوروارد‌شده از این مستأجر به آن آدرس ارسال خواهد شد.
• رد: نهایی است. دیگر هیچ‌گاه چیزی برای این مستأجر به آن آدرس فوروارد نمی‌شود و مستأجر نمی‌تواند دوباره برای آن درخواست تأیید بدهد.

دریافت یک مقصد فورواردکپی پیوند بخش

GET https://api.mail.land/v1/transactional/inbound/forward-destinations/{destinationId}

{
  "id": "f2k9m3q7p4w8x1",
  "email": "[email protected]",
  "status": "pending",
  "confirmedVia": null,
  "lastSentAt": "2026-09-26T10:00:00Z",
  "confirmedAt": null,
  "declinedAt": null
}

مقدار status یکی از pending، confirmed یا declined است. مقدار confirmedVia وقتی مالک از طریق ایمیل تأیید کرده باشد link است، وقتی آدرس روی یکی از دامنه‌های خودتان که برای ارسال تأیید شده باشد و نیازی به تأیید نداشته باشد verified_domain است، و در غیر این صورت null است. پاسخ یک مسیر نیز همین شیء را زیر forwardDestination حمل می‌کند (به پاسخ مسیر در ادامه مراجعه کنید).

ارسال دوبارهٔ تأییدکپی پیوند بخش

POST https://api.mail.land/v1/transactional/inbound/forward-destinations/{destinationId}/resend

فقط برای مقصدی که هنوز pending است و واقعاً به لینک نیاز دارد (آدرسی روی یکی از دامنه‌های ارسال تأیید‌شدهٔ خودتان مقدار 409 FORWARD_DESTINATION_NO_CONFIRMATION_NEEDED برمی‌گرداند، زیرا چیزی برای ارسال دوباره وجود ندارد). دارای محدودیت نرخ: حداکثر یک‌بار در هر ۵ دقیقه و ۵ بار در روز برای هر مقصد، و ۵۰ بار در روز برای کل مستأجر. عبور از هر یک از این محدودیت‌ها مقدار 429 FORWARD_CONFIRMATION_RATE_LIMITED برمی‌گرداند.

ایجاد یک مسیرکپی پیوند بخش

مسیرها به یک دامنه تعلق دارند و زیر همان دامنه ایجاد می‌شوند.

POST https://api.mail.land/v1/transactional/inbound/domains/{domainId}/routes

{
  "name": "Support Inbox",
  "matchType": "exact",
  "matchPattern": "support",
  "actions": ["store", "webhook"],
  "webhookId": "w4k8m2q7p9x3z1",
  "priority": 10
}

curl -X POST https://api.mail.land/v1/transactional/inbound/domains/k3v9x2m8q1w7z4/routes \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Support Inbox",
    "matchType": "exact",
    "matchPattern": "support",
    "actions": ["store", "webhook"],
    "webhookId": "w4k8m2q7p9x3z1",
    "priority": 10
  }'

پاسخکپی پیوند بخش

{
  "id": "r7k3m9q2p4w8x1",
  "name": "Support Inbox",
  "domainId": "k3v9x2m8q1w7z4",
  "domainName": "yourdomain.com",
  "priority": 10,
  "isEnabled": true,
  "matchType": "Exact",
  "matchPattern": "support",
  "actions": ["store", "webhook"],
  "webhookId": "w4k8m2q7p9x3z1",
  "webhookName": "Support Webhook",
  "webhookUrl": "https://yourapp.com/webhooks/support",
  "forwardToEmail": null,
  "forwardDestination": null,
  "rejectStatus": null,
  "rejectMessage": null,
  "createdAt": "2026-02-17T12:00:00Z",
  "updatedAt": "2026-02-17T12:00:00Z"
}

درخواست‌ها matchType را با هر حروف‌بزرگ‌وکوچکی می‌پذیرند؛ اما پاسخ‌ها همیشه نام enum را با حرف بزرگ ابتدایی برمی‌گردانند: Exact، Prefix، Suffix، Contains، PlusAddressing، CatchAll، Regex. مقدار matchType در پاسخ را با رشته‌ای با حروف کوچک مقایسه نکنید.

مقدار forwardDestination فقط زمانی پر می‌شود که actions شامل forward باشد؛ همان شیئی را حمل می‌کند که در دریافت یک مقصد فوروارد توضیح داده شد:

{
  "...": "...",
  "actions": ["store", "forward"],
  "forwardToEmail": "[email protected]",
  "forwardDestination": {
    "id": "f2k9m3q7p4w8x1",
    "email": "[email protected]",
    "status": "pending",
    "confirmedVia": null,
    "lastSentAt": "2026-09-26T10:00:00Z",
    "confirmedAt": null,
    "declinedAt": null
  }
}

فهرست مسیرهای یک دامنهکپی پیوند بخش

GET https://api.mail.land/v1/transactional/inbound/domains/{domainId}/routes

همهٔ مسیرهای دامنه را، به‌ترتیب اولویت (کوچک‌ترین ابتدا)، بازمی‌گرداند.

curl https://api.mail.land/v1/transactional/inbound/domains/k3v9x2m8q1w7z4/routes \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

{
  "items": [
    { "id": "r7k3m9q2p4w8x1", "name": "Support Inbox", "priority": 10, "isEnabled": true, "..." : "..." }
  ],
  "totalCount": 1
}

فهرست همهٔ مسیرهاکپی پیوند بخش

برای فهرست مسیرها در همهٔ دامنه‌های یک تننت، در عوض از نقطهٔ پایانی صفحه‌بندی‌شده با نشانگر استفاده کنید:

GET https://api.mail.land/v1/transactional/inbound/routes

دریافت جزئیات یک مسیرکپی پیوند بخش

GET https://api.mail.land/v1/transactional/inbound/routes/{routeId}

curl https://api.mail.land/v1/transactional/inbound/routes/r7k3m9q2p4w8x1 \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

به‌روزرسانی یک مسیرکپی پیوند بخش

PUT https://api.mail.land/v1/transactional/inbound/routes/{routeId}

بدنهٔ درخواست مانند درخواست ایجاد است، اما هر فیلد اختیاری است: فقط فیلدهایی که ارسال می‌کنید به‌روزرسانی می‌شوند.

curl -X PUT https://api.mail.land/v1/transactional/inbound/routes/r7k3m9q2p4w8x1 \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "matchPattern": "help",
    "priority": 5
  }'

فعال یا غیرفعال‌کردن یک مسیرکپی پیوند بخش

مقدار isEnabled را بدون تغییر سایر فیلدها معکوس می‌کند. بدون بدنهٔ درخواست.

POST https://api.mail.land/v1/transactional/inbound/routes/{routeId}/toggle

curl -X POST https://api.mail.land/v1/transactional/inbound/routes/r7k3m9q2p4w8x1/toggle \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

تغییر ترتیب مسیرهاکپی پیوند بخش

اولویت همهٔ مسیرهای یک دامنه را یکجا به‌روزرسانی کنید، با ارسال شناسه‌های مسیر به ترتیب دلخواه: اولین شناسه اولویت ۱، دومی اولویت ۲ می‌شود و به همین ترتیب ادامه می‌یابد.

POST https://api.mail.land/v1/transactional/inbound/domains/{domainId}/routes/reorder

{
  "routeIds": ["r7k3m9q2p4w8x1", "m2p8w4x1k7q3z9", "x4k1p7m3q9w2z8"]
}

curl -X POST https://api.mail.land/v1/transactional/inbound/domains/k3v9x2m8q1w7z4/routes/reorder \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "routeIds": ["r7k3m9q2p4w8x1", "m2p8w4x1k7q3z9", "x4k1p7m3q9w2z8"]
  }'

آزمایش یک مسیرکپی پیوند بخش

بدون پردازش یک ایمیل واقعی، بررسی کنید کدام مسیر با یک آدرس گیرندهٔ مشخص تطبیق دارد.

POST https://api.mail.land/v1/transactional/inbound/domains/{domainId}/routes/test

{
  "emailAddress": "[email protected]"
}

curl -X POST https://api.mail.land/v1/transactional/inbound/domains/k3v9x2m8q1w7z4/routes/test \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "emailAddress": "[email protected]"
  }'

{
  "matched": true,
  "matchedRouteId": "r7k3m9q2p4w8x1",
  "matchedRouteName": "Support Inbox",
  "actions": ["store", "webhook"]
}

اگر هیچ مسیری تطبیق نداشت، پاسخ 200 با matched: false است و matchedRouteId/matchedRouteName/actions همگی null هستند. 404 به این معناست که دامنه یافت نشد، یا آدرس آزمایش‌شده نامعتبر است (بدون @).

حذف یک مسیرکپی پیوند بخش

DELETE https://api.mail.land/v1/transactional/inbound/routes/{routeId}

curl -X DELETE https://api.mail.land/v1/transactional/inbound/routes/r7k3m9q2p4w8x1 \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

نمونه مسیرهاکپی پیوند بخش

مسیر همه‌شمول (catch-all): ذخیرهٔ هر گیرندهٔ تطبیق‌نیافته:

{
  "name": "Catch All",
  "matchType": "catchall",
  "matchPattern": "*",
  "actions": ["store"],
  "priority": 999
}

آدرس‌دهی با علامت جمع (plus-addressing): هدایت همهٔ انواع support+*@yourdomain.com به یک وب‌هوک:

{
  "name": "Support Tickets",
  "matchType": "plusaddressing",
  "matchPattern": "support",
  "actions": ["store", "webhook"],
  "webhookId": "w4k8m2q7p9x3z1",
  "priority": 5
}

رد در SMTP: رد ایمیل ارسالی به صندوقی بازنشسته، پیش از پذیرش آن:

{
  "name": "Retired Mailbox",
  "matchType": "exact",
  "matchPattern": "old-team",
  "actions": ["reject"],
  "rejectStatus": "550 5.1.1",
  "rejectMessage": "Mailbox does not exist",
  "priority": 1
}

نسخهٔ فوروارد‌شده چه شکلی داردکپی پیوند بخش

نسخهٔ فوروارد‌شده یک ایمیل تراکنشی تازه و معمولی است، نه رله‌ای خام از بایت‌های اصلی، که از دامنهٔ تأیید‌شدهٔ شما ارسال می‌شود تا بتواند DKIM و DMARC را نزد ارائه‌دهندهٔ صندوق پستی مقصد پاس کند:

• From: به‌صورت "<نام فرستندهٔ اصلی> via <آدرس تطبیق‌یافته>@<دامنهٔ شما>"، مثلاً "Jane Doe via [email protected]". نام نمایشی‌ای که شبیه آدرس باشد (شامل @، < یا >) با آدرس خالص اصلی جایگزین می‌شود تا هیچ نسخه‌ای نتواند زیر DKIM شما جای یک برند دیگر را بگیرد.
• Reply-To: اگر پیام اصلی Reply-To داشته باشد همان، وگرنه آدرس فرستندهٔ اصلی، تا پاسخ‌ها به نویسندهٔ واقعی برسد، نه به شما.
• بدون ردیابی: ردیابی بازشدن و کلیک در نسخهٔ فوروارد‌شده همیشه خاموش است، صرف‌نظر از تنظیمات ردیابی فضای کاری شما.
• بدون پانوشت برند: پانوشتی که ممکن است سایر ارسال‌ها در پلن رایگان داشته باشند هرگز افزوده نمی‌شود.
• پیوست‌ها: با همان قواعد یک ارسال بیرونی از طریق API فیلتر می‌شوند (نوع، تعداد، حجم کل). هرچه کنار گذاشته شود در یادداشتی در بالای نسخه ذکر می‌شود: "Forwarded without N attachment(s) that exceed the outbound attachment limits: ..."، نسخه در هر صورت می‌رسد، فقط بدون آن بخش‌ها.
• برچسب: هر نسخهٔ فوروارد‌شده برچسب inbound-forward را دارد تا بتوانید آن‌ها را در گزارش عادی پیام‌های خود پیدا کنید؛ وضعیت تحویل آن (queued، sent، delivered، bounced و غیره) همان وضعیتی است که هر ارسال تراکنشی دیگر می‌گیرد، چون از همان مسیر تحویل عبور می‌کند.
• مصرف: هر نسخهٔ فوروارد‌شده به‌عنوان یک ارسال در سهمیه و صورت‌حساب پلن شما محاسبه می‌شود و به‌صورت یک ردیف جداگانهٔ «Inbound forward» در مصرف نمایش داده می‌شود، جدا از ارسال‌های API، SMTP، کمپین و اتوماسیون.

چه چیزی هرگز فوروارد نمی‌شودکپی پیوند بخش

پیامی که با یک مسیر forward تطبیق دارد، در موارد زیر فوروارد نمی‌شود و هرگز فاکتور نمی‌شود:

• به‌عنوان اسپم علامت‌گذاری شده باشد، یا فرستنده به‌عنوان اسپم بلاک‌لیست شده باشد.
• در DMARC، بر پایهٔ سیاست مؤثر دامنهٔ فرستنده که quarantine یا reject است، رد شود؛ این سیاست با بالا رفتن از دامنهٔ فرستنده و یافتن نزدیک‌ترین رکورد قابل‌اعمال تعیین می‌شود، به‌طوری‌که sp= دامنهٔ فرعی بر p= دامنهٔ سازمانی آن اولویت دارد و رکورد t=y (آزمایشی) یا pct=0 یک سطح پایین‌تر از سیاست در نظر گرفته می‌شود؛ چون فورواردکردن آن به معنای امضای دوبارهٔ پیامی است که فرستنده‌اش صراحتاً از گیرندگان خواسته آن را رد کنند.
• خودِ آن یا بدنهٔ HTML/متنی‌اش از حدود حجم خروجی پلتفرم فراتر رود.
• فورواردکردن آن یک حلقه ایجاد کند: مقصد یکی از گیرندگان خودِ پیام باشد، یا پیام از پیش تعداد زیادی hop یا هدر Received داشته باشد.

نسخه‌ای که واجد شرایط است اما موقتاً قابل ارسال نیست (تأخیر یک سیاست، پنجرهٔ سهمیه، یک قطعی)، تا سقف ۲۴ ساعت با backoff دوباره تلاش می‌شود و سپس بدون ارسال منقضی می‌شود. مسیری که غیرفعال یا حذف شود، یا مقصدش پس از دریافت یک پیام تغییر کند، هر نسخهٔ همچنان منتظر را نیز متوقف می‌کند: پیکربندی فعلی مسیر همیشه مرجع است.

بررسی نتیجهٔ یک فورواردکپی پیوند بخش

هر ایمیل واردی که با یک مسیر forward مطابقت داشته باشد، یک آرایهٔ forwards در پاسخ جزئیات آن (GET /v1/transactional/inbound/emails/{id}) دارد: یک مورد برای هر مقصدی که پیام برای فوروارد به آن در صف قرار گرفته، تا ببینید واقعاً چه اتفاقی افتاده، نه فقط جایی که پیکربندی شده بود.

"forwards": [
  {
    "destination": "[email protected]",
    "status": "Admitted",
    "reason": null,
    "omittedAttachmentCount": 0,
    "messageId": "m_01hz3k...",
    "createdAt": "2026-09-26T10:00:00Z",
    "updatedAt": "2026-09-26T10:00:02Z"
  }
]

status یکی از موارد زیر است:

Pending، Processing و Deferred تنها وضعیت‌های غیرنهایی هستند، هر مقدار دیگری نهایی است.

پاسخ‌های خطای فورواردکپی پیوند بخش

پاسخ‌های خطاکپی پیوند بخش

گام‌های بعدیکپی پیوند بخش

• Inbound Overview: نحوهٔ کار پردازش ایمیل ورودی
• Inbound Webhooks: قالب و تحویل بار وب‌هوک
• Domains: پیکربندی رکوردهای MX برای ایمیل ورودی