قالب‌ها

قالب‌های ایمیل قابل استفاده مجدد با متغیرهای پویا ایجاد کنید. قالب‌ها موضوع، محتوای HTML و محتوای متنی ایمیل شما را ذخیره می‌کنند تا بتوانید ایمیل‌های شخصی‌سازی‌شده را بدون بازسازی محتوا در هر درخواست ارسال کنید.

ایجاد یک قالبکپی پیوند بخش

POST https://api.mail.land/v1/templates

curl -X POST https://api.mail.land/v1/templates \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Order Confirmation",
    "subject": "Your order #{{orderNumber}} is confirmed",
    "htmlContent": "<h1>Thanks, {{firstName}}!</h1><p>Order #{{orderNumber}} has been confirmed. Total: {{total}}</p>",
    "textContent": "Thanks, {{firstName}}! Order #{{orderNumber}} has been confirmed. Total: {{total}}",
    "categoryId": "k3v9q2m7xw4tpa"
  }'

{
  "id": "t8x2m4q9zk7wpr",
  "name": "Order Confirmation",
  "subject": "Your order #{{orderNumber}} is confirmed",
  "htmlContent": "<h1>Thanks, {{firstName}}!</h1>...",
  "textContent": "Thanks, {{firstName}}!...",
  "categoryId": "k3v9q2m7xw4tpa",
  "categoryName": "Transactional",
  "categoryColor": "#3B82F6",
  "createdAt": "2026-02-17T10:00:00Z",
  "updatedAt": null
}

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

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

از آکولادهای دوتایی برای جایگزینی متغیر استفاده کنید:

<h1>Hello {{firstName}},</h1>
<p>Your order #{{orderNumber}} shipped on {{shipDate}}.</p>
<p>Track your package: <a href="{{trackingUrl}}">{{trackingNumber}}</a></p>

متغیرها در زمان ارسال جایگزین می‌شوند. مقادیر را از طریق فیلد variables در درخواست ارسال خود ارائه دهید:

{
  "from": { "email": "[email protected]" },
  "to": [
    {
      "email": "[email protected]",
      "variables": {
        "firstName": "Jane",
        "orderNumber": "ORD-12345",
        "shipDate": "Feb 17, 2026",
        "trackingUrl": "https://track.example.com/ABC123",
        "trackingNumber": "ABC123"
      }
    }
  ],
  "templateId": "t8x2m4q9zk7wpr"
}

مقادیر پیش‌فرضکپی پیوند بخش

هر قالب می‌تواند برای هر فیلد مخاطبی که استفاده می‌کند یک مقدار پیش‌فرض داشته باشد، تا مشترکی که برای آن فیلد مقداری ندارد هم ایمیل را دریافت کند. آن را با variableDefaults تنظیم کنید، یک شیء از نام جایگزین به مقدار، هنگام ایجاد و به‌روزرسانی. هنگام دریافت، فهرست‌کردن یا تکثیر قالب هم برگردانده می‌شود.

{
  "name": "Welcome",
  "subject": "Hello {{firstName}}",
  "htmlContent": "<p>Hi {{firstName}}</p>",
  "variableDefaults": { "firstName": "دوست" }
}

قواعد:

• مقادیر پیش‌فرض فقط برای ارسال‌های کمپین و اتوماسیون اعمال می‌شوند. مقدار غیرخالیِ خودِ گیرنده همیشه بر پیش‌فرض برتری دارد.
• فیلدی که نه مقدار دارد و نه پیش‌فرض، همچنان رد می‌شود: MailLand هرگز {{firstName}} خام را نمی‌فرستد.
• ارسال‌های تراکنشی از طریق API و SMTP تحت‌تأثیر نیستند. در آن‌ها مقادیر از درخواست شما می‌آیند و مقدار نبودن، همان‌طور که بالا آمد رد می‌شود.
• در به‌روزرسانی، اگر variableDefaults را نفرستید پیش‌فرض‌های ذخیره‌شده می‌مانند. برای پاک‌کردنشان {} بفرستید.
• نام‌ها از نحو جایگزین‌ها پیروی می‌کنند. email و subscriberId همیشه تأمین می‌شوند و پیش‌فرض نمی‌گیرند. هر مقدار یک خط و حداکثر ۲۰۰ نویسه است و هر قالب حداکثر ۵۰ پیش‌فرض دارد.

در ویرایشگر داشبورد، برای هر جایگزین یک ورودی پیش‌فرض هست که تعداد مشترکان فاقد آن فیلد را نشان می‌دهد، و هنگام ذخیره اگر فیلدی که مشترک فاقد آن دارد پیش‌فرض نداشته باشد هشدار می‌دهد.

پیش‌نمایش یک قالبکپی پیوند بخش

پیش‌نمایش قالب با مقادیر نمونه که به‌طور خودکار برای متغیرهای شناسایی‌شده پر می‌شوند:

GET https://api.mail.land/v1/templates/{id}/preview

curl https://api.mail.land/v1/templates/t8x2m4q9zk7wpr/preview \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

{
  "id": "t8x2m4q9zk7wpr",
  "name": "Order Confirmation",
  "subject": "Your order #12345 is confirmed",
  "renderedHtml": "<h1>Thanks, John!</h1><p>Order #12345 has been confirmed.</p>",
  "renderedText": "Thanks, John! Order #12345 has been confirmed."
}

تکثیر یک قالبکپی پیوند بخش

یک قالب موجود را کلون کنید:

POST https://api.mail.land/v1/templates/{id}/duplicate

curl -X POST https://api.mail.land/v1/templates/t8x2m4q9zk7wpr/duplicate \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

نسخه تکثیرشده نام تولیدشده خودکار دریافت می‌کند: "Order Confirmation (Copy)". اگر یک نسخه از قبل موجود باشد، نام افزایش می‌یابد: "Order Confirmation (Copy 2)" و غیره.

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

قالب‌ها را با رنگ‌های اختیاری در دسته‌بندی‌ها سازماندهی کنید.

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

POST https://api.mail.land/v1/templates/categories

curl -X POST https://api.mail.land/v1/templates/categories \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Transactional",
    "description": "Order confirmations, receipts, and shipping notifications",
    "color": "#3B82F6"
  }'

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

GET https://api.mail.land/v1/templates/categories

curl https://api.mail.land/v1/templates/categories \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

{
  "categories": [
    {
      "id": "k3v9q2m7xw4tpa",
      "name": "Transactional",
      "description": "Order confirmations, receipts",
      "color": "#3B82F6",
      "templateCount": 12,
      "createdAt": "2026-01-15T10:00:00Z"
    }
  ],
  "totalCount": 3
}

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

GET https://api.mail.land/v1/templates?limit=50

curl "https://api.mail.land/v1/templates?limit=50" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

فیلتر بر اساس دسته‌بندی:

GET https://api.mail.land/v1/templates?categoryId=k3v9q2m7xw4tpa

curl "https://api.mail.land/v1/templates?categoryId=k3v9q2m7xw4tpa" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

{
  "items": [
    {
      "id": "t8x2m4q9zk7wpr",
      "name": "Order Confirmation",
      "subject": "Your order #{{orderNumber}} is confirmed",
      "htmlContent": "...",
      "categoryName": "Transactional",
      "categoryColor": "#3B82F6",
      "createdAt": "2026-02-17T10:00:00Z"
    }
  ],
  "nextCursor": "eyJ2IjoxLCJzIjoiY3JlYXRlZGF0OmRlc2MiLCJrIjoi...",
  "hasMore": true
}

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

PUT https://api.mail.land/v1/templates/{id}

تمام فیلدها در درخواست به‌روزرسانی الزامی هستند (این یک جایگزینی کامل است، نه به‌روزرسانی جزئی):

curl -X PUT https://api.mail.land/v1/templates/t8x2m4q9zk7wpr \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Order Confirmation v2",
    "subject": "Order #{{orderNumber}} confirmed - {{companyName}}",
    "htmlContent": "<h1>Thanks, {{firstName}}!</h1><p>Updated template content.</p>",
    "textContent": "Thanks, {{firstName}}! Updated template content.",
    "categoryId": "k3v9q2m7xw4tpa"
  }'

حذف یک قالبکپی پیوند بخش

DELETE https://api.mail.land/v1/templates/{id}

curl -X DELETE https://api.mail.land/v1/templates/t8x2m4q9zk7wpr \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

در صورت موفقیت 204 No Content برمی‌گردد. قالب حذف‌شده دیگر قابل بازیابی، فهرست‌کردن یا استفاده برای ارسال نیست: درخواست ارسالی که به آن اشاره می‌کند، چه فوری چه زمان‌بندی‌شده، با خطای 400 TEMPLATE_NOT_FOUND رد می‌شود؛ و زمان‌بندی‌ای که قالبش پیش از موعد حذف شود نیز دقیقاً همین‌طور در زمان ارسال رد می‌شود.

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

با ارجاع به یک قالب از طریق شناسه در درخواست ارسال خود، موضوع و محتوای قالب استفاده می‌شود و متغیرها جایگزین می‌شوند:

{
  "from": { "email": "[email protected]" },
  "to": [
    {
      "email": "[email protected]",
      "variables": {
        "firstName": "Jane",
        "orderNumber": "ORD-12345"
      }
    }
  ],
  "templateId": "t8x2m4q9zk7wpr",
  "variables": {
    "companyName": "Acme Inc"
  }
}

وقتی templateId تنظیم شده باشد، همیشه موضوع رندرشدهٔ قالب استفاده می‌شود؛ هر subject در درخواست ارسال نادیده گرفته می‌شود.

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

تعداد قالب‌هایی که می‌توانید ایجاد کنید به طرح شما بستگی دارد. اگر به محدودیت برسید، ایجاد یک قالب جدید 403 PLAN_LIMIT_REACHED را برمی‌گرداند.

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

• REST API: ارسال ایمیل با قالب‌ها
• ارسال دسته‌ای: استفاده از قالب‌ها با ایمیل‌های دسته‌ای
• ایمیل‌های زمان‌بندی‌شده: استفاده از قالب‌ها از طریق /v1/transactional/send همراه با scheduledAt (endpoint زمان‌بندی فیلد templateId ندارد)