مفاتيح API والخطافات

Mail Merge لديها REST API و خطافات صادرة للمطورين ومنشئي التطبيقات بدون كود. باستخدام مفتاح API يمكن لبرامجك أن تفعل ما تفعله تطبيق الويب: قراءة حسابك وإدراج القوالب والجهات الاتصال وإرسال الحملات ومتابعة المستقبلين. باستخدام خطاف يستدعي Mail Merge نقطة نهايتك في اللحظة التي تنتهي فيها الحملة أو يفتح المستقبل أو ينقر أو يرد أو يرتد أو يلغي الاشتراك، بحيث يبقى نظام إدارة علاقات العملاء أو جدول البيانات أو قناة Slack متزامنة دون الحاجة للاستطلاع.

كلاهما موجود تحت الإعدادات → المطورون في تطبيق الويب وهما جزء من خطة Professional (انظر التسعير). إذا كنت تفضل التحدث إلى Mail Merge من مساعد ذكاء اصطناعي بدلاً من كتابة الكود، استخدم خادم MCP بدلاً من ذلك: فهو يعرض نفس الميزات كأدوات، على كل الخطط.

مفاتيح API

إنشاء مفتاح

1. افتح الإعدادات → المطورون → مفاتيح API وانقر على إنشاء مفتاح.
2. سمه باسم المكان الذي سيتم استخدامه فيه (Zapier، مزامنة CRM)، حتى تتمكن من إلغاء المفتاح الصحيح لاحقاً.
3. انسخ المفتاح. يتم عرضه مرة واحدة فقط: Mail Merge يحتفظ فقط بـ hash له. إذا فقدته، ألغِ المفتاح وأنشئ واحداً جديداً.

يمكنك الحصول على ما يصل إلى 10 مفاتيح لكل حساب. إلغاء المفتاح يفشل كل طلب يتم إجراؤه معه على الفور؛ الصف يختفي من القائمة.

المصادقة

أرسل المفتاح كرمز Bearer على كل طلب، مقابل عنوان URL الأساسي المعروض على البطاقة:

curl https://merge.email/api/v1/me \
  -H "Authorization: Bearer mm_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

يعمل المفتاح كحساب أنشأه، تماماً مثل جلسة موقعة: نفس منحة Google، نفس الحصة اليومية، نفس حدود الخطة. لا يوجد “مستخدم API” منفصل.

نقاط النهاية

API هو نفس سطح /v1 الذي يستخدمه تطبيق الويب، لذا أي شيء يمكنك القيام به على الشاشة له نقطة نهاية خلفه. الأشياء التي تصل إليها التكاملات في الغالب:

الاستدعاء	ما يفعله
GET /v1/me	الحساب: الخطة، الحصة اليومية (الحد الأقصى، المستخدم، المتبقي)، المنطقة الزمنية، بيانات وصف القالب.
GET /v1/templates · GET /v1/templates/{templateId}	القوالب المحفوظة؛ يتم تحميل النص لكل قالب.
GET /v1/contacts · POST /v1/contacts	دفتر جهات الاتصال (مع ترقيم الصفحات باستخدام limit / cursor → nextCursor).
POST /v1/campaigns	إرسال أو جدولة أو أتمتة حملة من Google Sheets. النص هو نفسه الذي ينشره منشئ الحملة: الورقة، عمود المستقبل، الموضوع والنص مع {{merge tags}}، وخيارات الإرسال.
GET /v1/campaigns · GET /v1/campaigns/{campaignId}/recipients	حملاتك وحالة كل مستقبل (مرسل، مقروء، نقر عليه، رد عليه، ارتد، ألغى الاشتراك).
POST /v1/campaigns/{campaignId}/status	إيقاف أو استئناف أو إيقاف حملة قيد التشغيل.
POST /v1/recipients/verify	التحقق من البريد الإلكتروني.

أجسام الطلب والاستجابة بصيغة JSON. السطح المكتوب الكامل يتم إنشاؤه من الخادم كمستند OpenAPI؛ اتصل بنا إذا كنت بحاجة إلى المخطط لمولد عميل.

الأخطاء والحد من المعدل

الأعطال هي حالات HTTP حقيقية مع غلاف واحد:

{ "error": { "code": "professional_plan_required", "message": "API access is a Professional plan feature" } }

الحالة	code	المعنى
401		مفتاح غير معروف أو ملغى، أو يحتاج وصول Google للحساب إلى إعادة الاتصال.
403	professional_plan_required	حساب المفتاح لم يعد على خطة Professional. المفاتيح لا تُحذف عند الخفض؛ تعمل مرة أخرى عندما تعود الخطة.
429	rate_limited	أكثر من 600 طلب في الدقيقة على مفتاح واحد. انتظر دقيقة وأعد المحاولة.
400 / 404 / 409	bad_request, not_found, conflict, …	الطلب نفسه، مع رسالة توضح ما يجب إصلاحه.

يتم حساب حد المعدل لكل مفتاح على كل مثيل خادم API، لذا السقف الفعلي هو “حوالي 600 في الدقيقة”: لا تصمم حول الوصول إليه.

الخطافات

إضافة نقطة نهاية

1. افتح الإعدادات → المطورون → الخطافات وانقر على إضافة خطاف.
2. أدخل عنوان URL HTTPS (عادي http:// مرفوض) وحدد الأحداث التي يجب أن تستقبلها.
3. انقر على إرسال اختبار على الصف الجديد: Mail Merge ينشر ping والإشعار يخبرك كيف أجابت نقطة النهاية.

كل نقطة نهاية تحصل على سر التوقيع الخاص بها (whsec_…)، معروض على الصف مع زر النسخ. يمكنك الحصول على ما يصل إلى 5 نقاط نهاية لكل حساب.

الأحداث

الحدث	متى	data
campaign.completed	تم معالجة آخر بريد إلكتروني في الحملة.	campaignId, name, status: "completed", sentCount, campaignSize
campaign.paused · campaign.resumed · campaign.stopped	أوقفت أو استأنفت أو أيقفت حملة.	campaignId, name, status (paused / active / stopped), sentCount
email.opened	فتح المستقبل بريداً إلكترونياً، مرة واحدة فقط لكل حملة.	campaignId, recipient, at
email.clicked	نقر المستقبل على رابط متتبع، كل نقرة.	campaignId, recipient, at, url
email.replied	تم اكتشاف رد على خيط مرسل.	campaignId, recipient, at
email.bounced	تم اكتشاف ارتداد.	campaignId, recipient, at
recipient.unsubscribed	استخدم المستقبل رابط إلغاء الاشتراك، مرة واحدة فقط لكل حملة.	campaignId, recipient, at, method

الفتح والنقر يحتاجان إلى التتبع مفعل للحملة؛ الردود والارتدادات تأتي من مسح الرد الذي يتبع كل حملة مرسلة.

التسليم

Mail Merge يرسل POST واحد لكل حدث لكل نقطة نهاية مشترك، مع جسم JSON:

{
  "id": "6f1c2d3e-…",
  "event": "email.opened",
  "createdAt": "2026-10-15T14:03:21.512Z",
  "data": { "campaignId": "…", "recipient": "ada@example.com", "at": "2026-10-15T14:03:21.498Z" }
}

وثلاث رؤوس:

الرأس	القيمة
X-MailMerge-Event	اسم الحدث، نفس event في الجسم.
X-MailMerge-Delivery	معرف التسليم، نفس id. استخدمه لتجاهل نسخة مكررة.
X-MailMerge-Signature	sha256= متبوعاً بـ hex HMAC-SHA256 للجسم الخام، مفتاح بسر نقطة النهاية.

أجب بأي 2xx خلال 5 ثوان. عند خطأ شبكة أو 5xx يعيد Mail Merge المحاولة مرة واحدة، بعد ثانيتين؛ يتم أخذ 4xx كحكمك ولا تتم إعادة محاولته. نفس معرف التسليم يتم إرساله عند إعادة المحاولة. بعد 20 تسليم فاشل متتالي يتم تعطيل نقطة النهاية والصف يقول ذلك: أصلح نقطة النهاية، ثم احذفها وأضفها مرة أخرى. أي تسليم ناجح يعيد تعيين العداد.

يتم تسليم الأحداث مرة واحدة على الأقل وبدون ترتيب مضمون. الفتح بشكل خاص يصل في دفعات (كل عميل بريد يعرض بكسل التتبع)، لذا اجعل معالجك idempotent على X-MailMerge-Delivery أو على (event, campaignId, recipient).

التحقق من التوقيع

تحقق دائماً قبل الوثوق بـ payload. احسب HMAC على جسم الطلب الخام (البايتات الدقيقة، قبل أي تحليل JSON) وقارنه في وقت ثابت:

// Node.js (Express مع `express.raw({ type: "application/json" })`)
import { createHmac, timingSafeEqual } from "node:crypto"

export function verifyMailMergeSignature(rawBody, signatureHeader, secret) {
  const expected = "sha256=" + createHmac("sha256", secret).update(rawBody).digest("hex")
  const a = Buffer.from(expected)
  const b = Buffer.from(signatureHeader ?? "")
  return a.length === b.length && timingSafeEqual(a, b)
}

app.post("/mailmerge", (req, res) => {
  if (!verifyMailMergeSignature(req.body, req.get("X-MailMerge-Signature"), process.env.MAILMERGE_WEBHOOK_SECRET)) {
    return res.status(401).end()
  }
  const payload = JSON.parse(req.body)
  // … handle payload.event / payload.data
  res.status(204).end()
})

# Python
import hashlib, hmac

def verify_mailmerge_signature(raw_body: bytes, signature_header: str, secret: str) -> bool:
    expected = "sha256=" + hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, signature_header or "")

Zapier و Make و n8n

لا حاجة للكود: أنشئ Catch Hook (Zapier Webhooks by Zapier)، Custom webhook (Make) أو عقدة Webhook trigger (n8n)، الصق عنوان URL الذي يعطيك إياه كنقطة النهاية، حدد الأحداث، وانقر على إرسال اختبار حتى تتمكن الأداة من أخذ عينة من payload. حقول data تصبح المتغيرات التي تعينها في الخطوة التالية (أضف صفاً إلى ورقة، حدّث جهة اتصال CRM، انشر على Slack). هذه الأدوات لا تتحقق من التوقيعات بشكل افتراضي؛ عنوان URL الذي تعطيك إياه لا يمكن تخمينه، وهذا هو الحماية التي تعتمد عليها.

الخطوات التالية

• وكلاء الذكاء الاصطناعي (MCP)، إذا كان يجب على مساعد أن يقود Mail Merge بدلاً من البرنامج.
• الحملات، لمعرفة معنى الحالات في نقطة نهاية المستقبلين.
• التسعير، لمعرفة ما تتضمنه خطة Professional.