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

هنگامی که یک ایمیل ورودی با مسیری تطبیق داشته باشد که در actions آن webhook وجود دارد، MailLand ایمیل پردازش‌شده را به‌صورت یک درخواست POST با فرمت JSON به وب‌هوک همان مسیر ارسال می‌کند. این صفحه قالب بار، تأیید امضا و رفتار تحویل را پوشش می‌دهد.

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

MailLand یک درخواست POST با بدنهٔ JSON زیر به آدرس وب‌هوک شما ارسال می‌کند:

{
  "event": "inbound.received",
  "event_id": "evt_a1b2c3d4e5f60718293a4b5c6d7e8f90",
  "timestamp": "2026-02-17T14:30:00Z",
  "occurred_at": "2026-02-17T14:29:58Z",
  "schema_version": 1,
  "data": {
    "idempotency_key": "k7m2x9q4p1w8z3_r7k3m9q2p4w8x1",
    "email": {
      "id": "k7m2x9q4p1w8z3",
      "received_at": "2026-02-17T14:29:58Z",
      "size_bytes": 48213,
      "envelope": {
        "from": "[email protected]",
        "to": ["[email protected]"]
      },
      "headers": {
        "from": { "address": "[email protected]", "name": "Jane Customer" },
        "to": [{ "address": "[email protected]", "name": null }],
        "cc": [],
        "subject": "Need help with my account",
        "message_id": "<[email protected]>",
        "in_reply_to": null,
        "reply_to": "[email protected]",
        "date": "2026-02-17T14:29:55Z"
      },
      "body": {
        "text_preview": "I need assistance with my account settings.",
        "has_text": true,
        "has_html": true
      },
      "attachments": [
        {
          "id": "a3k7m2q9p4w1x8",
          "file_name": "screenshot.png",
          "content_type": "image/png",
          "size_bytes": 34500,
          "is_inline": false,
          "content_id": null,
          "download_url": "https://r2.example.com/screenshot.png?X-Amz-Signature=..."
        }
      ],
      "authentication": {
        "spf": { "result": "pass" },
        "dkim": { "result": "pass" },
        "dmarc": { "result": "pass" }
      },
      "spam": {
        "score": 1.2,
        "is_spam": false,
        "reason": null
      },
      "source": {
        "ip": "203.0.113.42",
        "hostname": "mail.example.com"
      }
    },
    "matched_route": {
      "id": "r7k3m9q2p4w8x1",
      "name": "Support Inbox"
    }
  }
}

متن کامل ایمیل هرگز درون بار قرار داده نمی‌شود: فقط یک پیش‌نمایش کوتاه‌شده در text_preview و پرچم‌های has_text/has_html. هیچ فیلد body.html وجود ندارد.

فیلدهایی که مقدار ندارند (name، in_reply_to، content_id، reason، data.matched_route و مانند آن‌ها) به‌جای ارسال به‌صورت null، کاملاً از JSON حذف می‌شوند. نمونهٔ بالا برای خوانایی null را نشان می‌دهد؛ روی حضور کلید حساب نکنید.

فیلدهای بارکپی پیوند بخش

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

محتوای پیوست‌ها هرگز درون بار قرار داده نمی‌شود. هر آیتم در data.email.attachments یک download_url دارد:

GET https://api.mail.land/v1/transactional/inbound/emails/{emailId}/raw

تأیید امضاکپی پیوند بخش

وب‌هوک‌های ورودی دقیقاً مانند هر وب‌هوک دیگر در MailLand امضا می‌شوند: همان سرصفحه، همان طرح، همان مدیریت راز. مرجع اصلی، همراه با یک مثال کامل و کد تأیید به هشت زبان، صفحهٔ Signature Verification است؛ همهٔ آنچه در آنجا آمده، بدون تغییر اینجا نیز صدق می‌کند.

خلاصه:

X-MLND-Signature: t=1708171200,v1=<hex>

• t یک زمان یونیکس بر حسب ثانیه است و v1 یک HMAC-SHA256 به‌صورت هگزادسیمال با حروف کوچک است؛
• رشتهٔ امضاشده به‌صورت {timestamp}.{raw_body} است: زمان، سپس یک نقطهٔ واقعی، و سپس بدنه دقیقاً همان‌طور که دریافت شده، پیش از تجزیهٔ JSON؛
• کلید، رازِ امضای وب‌هوک است که فقط یک‌بار هنگام ایجاد نمایش داده می‌شود؛
• مقایسه را در زمان ثابت انجام دهید و زمانی قدیمی‌تر از ۳۰۰ ثانیه را رد کنید.

رفتار تحویلکپی پیوند بخش

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

نقطهٔ پایانی شما باید با یک کد وضعیت 2xx برای تأیید دریافت پاسخ دهد. هر چیز دیگری، وضعیتی غیر از 2xx یا اتمام مهلت، به‌عنوان یک تلاش تحویل ناموفق شمرده می‌شود.

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

یک تلاش ناموفق با همان زمان‌بندی سایر رویدادهای وب‌هوک دوباره انجام می‌شود، تا سقف ۶ تلاش در مجموع برای هر رویداد: تلاش اول، سپس تلاش مجدد بلافاصله، بعد از ۱ دقیقه، ۵ دقیقه، ۱۵ دقیقه و ۱ ساعت. پس از ششمین تلاش ناموفق، تحویل به‌عنوان ناموفق دائمی علامت‌گذاری می‌شود. می‌توانید آن را به‌صورت دستی بازپخش کنید. برای زمان‌بندی کامل به منطق تلاش مجدد نگاه کنید.

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

تحویل مجدد وب‌هوک برای یک ایمیل ورودی مشخص:

POST https://api.mail.land/v1/transactional/inbound/emails/{id}/replay-webhook

curl -X POST https://api.mail.land/v1/transactional/inbound/emails/k7m2x9q4p1w8z3/replay-webhook \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

{
  "emailId": "k7m2x9q4p1w8z3",
  "queued": true,
  "webhookUrl": "https://yourapp.com/webhooks/support",
  "message": "Webhook replay queued successfully"
}

این درخواست یک تحویل پایدار را به وب‌هوک مسیر منطبق در صف قرار می‌دهد و پس از ثبت‌شدن همان سطر، 202 Accepted برمی‌گرداند؛ ارسال به‌صورت هم‌زمان انجام نمی‌شود. بازپخش یک شناسهٔ رویداد جدید می‌گیرد (event_id و X-MLND-Event-Id تازه) و شناسهٔ تحویل اصلی را در data.replay_of همراه دارد؛ بنابراین حذف تکراری‌ها در سمت شما آن را رویدادی جدید می‌بیند، ولی همچنان می‌توانید آن را به رویداد اصلی ربط دهید. data.idempotency_key همان مقدار تحویل اصلی باقی می‌ماند. درخواست هدرهای X-MLND-Source: inbound و X-MLND-Inbound-Email-Id را دارد و هر download_url پیوست در محموله در لحظهٔ ارسال امضا می‌شود؛ اعتبار آن ۱۵ دقیقه از همان لحظه است، نه از لحظهٔ فراخوانی بازپخش.

حذف رویدادهای تکراریکپی پیوند بخش

تحویل وب‌هوک ورودی حداقل یک‌بار (at-least-once) انجام می‌شود: تلاش مجدد، تایم‌اوت در سمت شما پس از پردازش درخواست، یا جابه‌جایی کارگر می‌تواند یک رویداد را بیش از یک بار تحویل دهد. گیرنده باید تکراری‌ها را حذف کند.

• هر وب‌هوک ورودی یک شناسهٔ رویداد ثابت دارد که در event_id و هدر X-MLND-Event-Id می‌آید. این شناسه برای هر پیام ورودی و هر وب‌هوک قطعی است؛ پس همهٔ تلاش‌های تحویل یک پیام به یک وب‌هوک شناسهٔ یکسان دارند.
• بر اساس همین شناسه تکراری‌ها را حذف کنید. شناسه‌های پردازش‌شده را نگه دارید و شناسه‌ای را که قبلاً دیده‌اید رد کنید.
• بازپخش دستی یک رویداد جدید است. event_id تازه دارد و فیلد data.replay_of شناسهٔ اصلی را نگه می‌دارد. اگر می‌خواهید بازپخشِ رویدادی که قبلاً پردازش شده نادیده گرفته شود، data.replay_of را هم با شناسه‌های ذخیره‌شده‌تان مقایسه کنید.

app.post("/webhooks/support", express.raw({ type: "application/json" }), async (req, res) => {
  // 1. Verify X-MLND-Signature first (see Signature Verification).
  const eventId = req.header("X-MLND-Event-Id");
  const client = await db.connect();
  try {
    await client.query("BEGIN");
    // 2. Record the event id; the unique constraint makes this atomic.
    const inserted = await client.query(
      "INSERT INTO processed_events (event_id) VALUES ($1) ON CONFLICT (event_id) DO NOTHING",
      [eventId],
    );
    // 3. Only a first-time id enqueues work, in the SAME transaction (jobs table).
    if (inserted.rowCount > 0) {
      await client.query("INSERT INTO jobs (kind, payload) VALUES ($1, $2)", [
        "process-inbound-email",
        req.body.toString(),
      ]);
    }
    await client.query("COMMIT");
    res.sendStatus(200); // new or duplicate: acknowledge
  } catch (err) {
    await client.query("ROLLBACK"); // id and job are both undone, so the retry is not a "duplicate"
    res.sendStatus(500);
  } finally {
    client.release();
  }
});

ثبت شناسه و صف‌گذاری کار در یک تراکنش اهمیت دارد: اگر شناسه اول ذخیره شود و صف‌گذاری شکست بخورد، تلاش مجدد MailLand به‌عنوان تکراری رد می‌شود و ایمیل از دست می‌رود.

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

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

هر درخواست وب‌هوک شامل سرصفحه‌های زیر است:

بهترین شیوه‌هاکپی پیوند بخش

• سریع پاسخ دهید: وب‌هوک را بلافاصله با 200 تأیید کنید و ایمیل را به‌صورت ناهم‌زمان در یک کار پس‌زمینه پردازش کنید.
• امضاها را تأیید کنید: همیشه سرصفحهٔ X-MLND-Signature را برای جلوگیری از بارهای جعلی اعتبارسنجی کنید.
• موارد تکراری را مدیریت کنید: تحویل حداقل یک‌بار است؛ پس بر اساس X-MLND-Event-Id (همان event_id محموله) تکراری‌ها را حذف کنید. بازپخش دستی شناسهٔ جدید دارد و data.replay_of آن شناسهٔ اصلی است؛ بخش حذف رویدادهای تکراری را ببینید.
• پیوست‌ها را فوراً دانلود کنید: هر download_url ۱۵ دقیقه پس از تولید بار منقضی می‌شود؛ پس از آن پیام خام را دریافت کنید.
• از HTTPS استفاده کنید: آدرس‌های وب‌هوک باید در محیط تولید از HTTPS برای تحویل امن بار استفاده کنند.

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

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

• Inbound Overview: پیکربندی تنظیمات ورودی و مشاهدهٔ ایمیل‌ها
• Inbound Routes: تنظیم قوانین مسیریابی برای تحویل وب‌هوک
• Webhooks: پیکربندی وب‌هوک‌های خروجی برای رویدادهای ایمیل