القوالب

أنشئ قوالب بريد إلكتروني قابلة لإعادة الاستخدام مع متغيرات ديناميكية. تخزّن القوالب موضوع بريدك الإلكتروني ومحتوى 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 دائماً ولا تُعطى لهما قيمة افتراضية. القيمة سطر واحد بحد أقصى 200 حرف، وللقالب 50 قيمة افتراضية كحد أقصى.

في محرر لوحة التحكم، لكل عنصر نائب حقل إدخال للقيمة الافتراضية يعرض عدد المشتركين الذين ينقصهم هذا الحقل، ويحذّرك الحفظ إذا كان حقل ينقص بعض المشتركين دون قيمة افتراضية.

معاينة قالبنسخ رابط القسم

معاينة القالب مع قيم نموذجية مملوءة تلقائيًا للمتغيرات المكتشفة:

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 (نقطة نهاية الجدولة لا تملك حقل templateId)