REST API

ایمیل‌های تراکنشی را از طریق POST /v1/transactional/send ارسال کنید. این روش اصلی ارسال ایمیل از طریق MailLand است.

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

کلید API خود را در هدر X-API-Key قرار دهید:

X-API-Key: ml_pet_Ab3Kx9mN2pQ7rT4wL8yD...

اعتبارنامه باید کانال Api فعال داشته باشد و از نوع اعتبارنامه محصول Sending باشد.

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

POST https://api.mail.land/v1/transactional/send

curl -X POST https://api.mail.land/v1/transactional/send \
  -H "X-API-Key: ml_pet_Ab3Kx9mN2pQ7rT4wL8yD..." \
  -H "Content-Type: application/json" \
  -d '{
    "from": {"email": "[email protected]"},
    "to": [{"email": "[email protected]"}],
    "subject": "Hello from MailLand",
    "htmlContent": "<p>Your email content here</p>"
  }'

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

{
  "from": {
    "email": "[email protected]",
    "name": "Your App"
  },
  "to": [
    {
      "email": "[email protected]",
      "name": "Jane Doe",
      "variables": {
        "firstName": "Jane",
        "orderNumber": "ORD-12345"
      }
    }
  ],
  "subject": "Your order #{{orderNumber}} has shipped",
  "htmlContent": "<h1>Hi {{firstName}},</h1><p>Your order #{{orderNumber}} is on its way.</p>",
  "textContent": "Hi {{firstName}}, Your order #{{orderNumber}} is on its way.",
  "replyTo": "[email protected]",
  "tags": ["order-shipped", "transactional"],
  "customHeaders": {
    "X-Entity-Ref-ID": "order-12345"
  },
  "tracking": {
    "opens": true,
    "clicks": true
  },
  "priority": "High",
  "idempotencyKey": "order-12345-shipped-v1"
}

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

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

هر پیوست به سه فیلد نیاز دارد:

{
  "attachments": [
    {
      "fileName": "invoice.pdf",
      "contentType": "application/pdf",
      "content": "JVBERi0xLjQKJ...",
      "inline": false
    },
    {
      "fileName": "logo.png",
      "contentType": "image/png",
      "content": "iVBORw0KGgoAAAA...",
      "contentId": "company-logo",
      "inline": true
    }
  ]
}

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

وضعیت: 202 Accepted

{
  "success": true,
  "jobId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "messageIds": ["t_a1b2c3d4e5f6..."],
  "acceptedRecipients": ["[email protected]"],
  "rejectedRecipients": [],
  "queuedAt": "2026-02-17T10:30:00Z",
  "isSandboxed": false
}

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

گیرندگان می‌توانند به چند دلیل رد شوند:

{
  "success": true,
  "jobId": "...",
  "acceptedRecipients": ["[email protected]"],
  "rejectedRecipients": [
    {
      "email": "[email protected]",
      "reason": "Suppressed"
    },
    {
      "email": "[email protected]",
      "reason": "domain_typo",
      "suggestion": "[email protected]"
    }
  ]
}

دلایل رایج رد:

• Suppressed: آدرس در لیست سرکوب است (بانس یا شکایت‌های قبلی)
• disposable_domain: ارائه‌دهنده ایمیل یکبارمصرف شناسایی شد
• domain_typo: احتمالاً اشتباه تایپی در دامنه (شامل فیلد suggestion)

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

توانایی ارسال خود را قبل از درخواست واقعی تأیید کنید:

GET https://api.mail.land/v1/transactional/send/check?recipientCount=1

curl https://api.mail.land/v1/transactional/send/check?recipientCount=1 \
  -H "X-API-Key: ml_pet_Ab3Kx9mN2pQ7rT4wL8yD..."

{
  "canSend": true,
  "rateLimitStatus": {
    "currentSecond": 2,
    "limitPerSecond": 50,
    "currentHour": 450,
    "limitPerHour": 5000,
    "currentDay": 8200,
    "limitPerDay": 50000
  },
  "monthlyUsed": 125000,
  "monthlyLimit": 500000
}

اگر canSend برابر false باشد، فیلد reason دلیل آن را توضیح می‌دهد (محدودیت نرخ، سهمیه، وضعیت حساب و غیره).

ایدمپوتنسی (Idempotency)کپی پیوند بخش

تلاش دوباره برای ارسال پس از پایان مهلت شبکه نباید ایمیل را دو بار تحویل دهد. با دادن کلید ایدمپوتنسی، تلاش دوباره به‌جای ارسال مجدد، پاسخ اصلی را بازپخش می‌کند.

کلید را به‌صورت هدر بفرستید (توصیه‌شده):

X-Idempotency-Key: order-12345-shipped-v1

یا از فیلد idempotencyKey در بدنه استفاده کنید. هر دو پذیرفته می‌شوند و ارسال هم‌زمانِ هر دو تنها در صورت یکسان بودن مقادیر مجاز است.

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

• دامنه. X-Idempotency-Key تنها روی POST /v1/transactional/send و POST /v1/transactional/send-batch پذیرفته می‌شود و هیچ نقطهٔ پایانی دیگری آن را نمی‌خواند.
• قالب. ۱ تا ۲۵۵ نویسه: حروف، ارقام، _ و -. کلیدها دقیقاً مقایسه می‌شوند؛ بدون حذف فاصله و بدون یکسان‌سازی بزرگی و کوچکی حروف.
• بازه. هر کلید تا ۲۴ ساعت قابل بازپخش است. پس از آن همان کلید یک درخواست تازه به شمار می‌رود.
• بازپخش. تلاش دوباره در این بازه، پاسخ اصلی را عیناً برمی‌گرداند، همان شناسه‌ها و همان وضعیت، و چیزی ارسال نمی‌کند.
• یکتایی. کلیدها به ازای هر حساب یکتا هستند. استفادهٔ دوباره از یک کلید برای نقطهٔ پایانی دیگر با 409 رد می‌شود؛ برای هر عملیات کلید جداگانه به کار ببرید.

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

درخواست‌ها را در سیستم‌ها با افزودن یک شناسه همبستگی ردیابی کنید:

X-Correlation-ID: my-app-order-12345

یا

X-Request-ID: my-app-order-12345

شناسهٔ همبستگی در لاگ‌ها و جریان فعالیت ظاهر می‌شود.

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

پاسخ‌های موفق شامل اطلاعات محدودیت نرخ به‌ازای هر IP هستند:

X-RateLimit-Limit: 300
X-RateLimit-Remaining: 295

هنگامی که موتور سیاست ارسال محدودیت نرخ را اعمال می‌کند (429)، هدر Retry-After ثانیه‌های انتظار را نشان می‌دهد:

Retry-After: 30

یک درخواست تراکنشی می‌تواند تا ۵ گیرنده داشته باشد و هر گیرنده در محدودیت‌های نرخ شما شمرده می‌شود. اگر این تعداد از سهمیهٔ در ثانیهٔ شما بیشتر باشد (برای مثال ۱ در ثانیه در پلنی با ۶۰ در دقیقه)، درخواست وقتی پذیرفته می‌شود که در همان ثانیه درخواست دیگری پذیرفته نشده باشد؛ در غیر این صورت پاسخ 429 با Retry-After: 1 می‌گیرد و با تلاش دوباره در ثانیهٔ بعد، در حد محدودیت دقیقه‌ای شما، موفق می‌شود. به محدودیت‌های نرخ مراجعه کنید.

یک 429 در سطح IP همچنین شامل X-RateLimit-Reset به‌صورت زمان UTC با قالب ISO-8601 است.

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

تمام خطاها یک بدنهٔ JSON برمی‌گردانند:

{
  "code": "ERROR_CODE",
  "message": "Human-readable description",
  "timestamp": "2026-02-17T10:30:00Z",
  "traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01"
}

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

محدودیت گیرندگان تراکنشیکپی پیوند بخش

اعتبارنامه‌های تراکنشی حداکثر ۵ گیرنده در هر درخواست ارسال را اجرا می‌کنند. این امر از سوءاستفاده از جریان‌های تراکنشی برای ارسال انبوه جلوگیری می‌کند. اگر به گیرندگان بیشتری نیاز دارید، از اعتبارنامه بازاریابی با ارسال دسته‌ای استفاده کنید.

استفاده از قالب‌هاکپی پیوند بخش

به جای HTML درون‌خطی، به یک قالب ذخیره‌شده ارجاع دهید:

{
  "from": { "email": "[email protected]" },
  "to": [
    {
      "email": "[email protected]",
      "variables": {
        "firstName": "Jane",
        "resetLink": "https://app.example.com/reset?token=abc123"
      }
    }
  ],
  "templateId": "t8x2m4q9zk7wpr",
  "variables": {
    "companyName": "Acme Inc"
  }
}

subject از قالب می‌آید. در صورت هم‌پوشانی کلید، مقدار to[].variables خودِ گیرنده، variables سراسری را بازنویسی می‌کند، همان قاعدهٔ محتوای درون‌خطی. برای ایجاد و مدیریت قالب‌ها به قالب‌ها مراجعه کنید.

مراحل بعدیکپی پیوند بخش

• ارسال دسته‌ای: ارسال به چندین گیرنده به یکباره
• رله SMTP: ارسال از طریق SMTP به جای REST
• قالب‌ها: ایجاد قالب‌های ایمیل قابل استفاده مجدد
• ایمیل‌های زمان‌بندی شده: زمان‌بندی ایمیل‌ها برای تحویل آینده