كيفية الحصول على مفتاح API Resend وإرسال أول بريد إلكتروني

Resend هو واجهة برمجة تطبيقات (API) للبريد الإلكتروني مصممة للمطورين: طلب POST واحد، وهيكل JSON واحد، وينطلق بريد إلكتروني تفاعلي. يحتاج كل طلب إلى مفتاح API، وكيفية إنشاء هذا المفتاح تحدد مدى الضرر الذي يمكن أن يسببه مفتاح مسرب. يرشدك هذا الدليل خلال المسار بأكمله: التسجيل، والتحقق من نطاق الإرسال (أو الاعتماد على عنوان الاختبار المدمج)، وإنشاء مفتاح بنطاق الأذونات الصحيح، وإرسال أول بريد إلكتروني لك باستخدام curl و Node و Python. ستقوم أيضًا بتخزين المفتاح في Apidog حتى تتمكن من اختبار نقطة النهاية دون لصق الأسرار في سطر الأوامر الخاص بك.

إذا كنت تريد صورة أوسع لما تفعله واجهة برمجة التطبيقات (API) بخلاف الإرسال، فإن دليل المبتدئين الخاص بواجهة برمجة تطبيقات Resend يغطي البقية. تم التحقق من كل ما هو أدناه مقابل وثائق Resend الرسمية، لذا تتطابق الأرقام وسلاسل الأخطاء مع ما ستراه.

ما تحتاجه قبل البدء

• حساب Resend. الخطة المجانية كافية لهذا البرنامج التعليمي.
• نطاق تتحكم فيه. إذا لم يكن لديك واحد جاهز، فإن عنوان الاختبار يغطي الإرسال الأول.
• curl على جهازك، بالإضافة إلى Node.js أو Python إذا كنت تريد أمثلة SDK.
• Apidog مثبتًا إذا كنت تخطط لمتابعة قسم الاختبار.

الخطوة 1: إنشاء حساب Resend

سجل في resend.com وقم بتأكيد بريدك الإلكتروني. دوّن العنوان الذي سجلت به: حتى تقوم بالتحقق من نطاق، سيكون هو صندوق البريد الوحيد الذي سيقوم Resend بتسليم رسائل البريد الإلكتروني التجريبية إليه، ونسيان ذلك يسبب أكثر الأخطاء 403 إرباكًا قد تراها في اليوم الأول.

الخطوة 2: التحقق من نطاق الإرسال، أو استخدام عنوان الاختبار

طريقتان؛ ابدأ بالطريقة الأسرع.

الطريقة أ: عنوان اختبار الإعداد. يتيح لك Resend الإرسال من onboarding@resend.dev دون أي إعداد. المشكلة هي المستلم: يجب أن يكون عنوان البريد الإلكتروني لحسابك الخاص. أرسل إلى أي شخص آخر وستعيد واجهة برمجة التطبيقات (API) الخطأ 403 مع الرسالة "لا يمكنك إرسال رسائل بريد إلكتروني تجريبية إلا إلى عنوان بريدك الإلكتروني الخاص".

الطريقة ب: نطاقك الخاص. لأي شيء حقيقي، أضف نطاقًا في لوحة التحكم ضمن "Domains" (النطاقات). يوصي Resend باستخدام نطاق فرعي مثل notifications.example.com بدلاً من نطاقك الرئيسي، حتى تظل سمعة إرسال منتجك منفصلة عن بريدك المؤسسي. اختر المنطقة الأقرب إلى المستلمين، ثم انسخ سجلات DNS التي ينشئها Resend إلى مزود DNS الخاص بك. تصف الوثائق هذه السجلات بأنها "تكوينات DKIM و SPF (سجلات TXT و MX أو CNAME)". يكون النطاق الفرعي لـ Return-Path افتراضيًا send.example.com.

عادة ما يكتمل التحقق في غضون 15 دقيقة، على الرغم من أن نشر DNS قد يستغرق ما يصل إلى 72 ساعة. إذا توقف، تحقق من سببين كلاسيكيين: السجلات الموضوعة على الجذر بدلاً من النطاق الفرعي send، ووكل Cloudflare (يجب أن تكون أيقونة السحابة رمادية، وليست برتقالية). أصلح السجلات، ثم انقر على "إعادة تشغيل التحقق". أضف سجل DMARC بعد ذلك؛ إنه ليس مطلوبًا للإرسال، لكن مزودي صناديق البريد يكافئون استخدامه.

الخطوة 3: إنشاء مفتاح API بالنطاق الصحيح

افتح صفحة مفاتيح API في لوحة التحكم وانقر على "Create API Key" (إنشاء مفتاح API). ثلاثة حقول مهمة؛ يغطي مستند إنشاء مفتاح API كل منها:

• الاسم. حتى 50 حرفًا. سمه باسم التطبيق والبيئة، مثل billing-service-prod، حتى يسهل تمييز المفاتيح لاحقًا.
• الإذن. يمكن "الوصول الكامل" (Full access) إنشاء، حذف، الحصول على، وتحديث أي مورد، بما في ذلك النطاقات ومفاتيح API الأخرى. يمكن "وصول الإرسال" (Sending access) إرسال رسائل البريد الإلكتروني فقط. اختر وصول الإرسال لأي شيء يتم نشره. ينتمي مفتاح الوصول الكامل إلى جهاز الكمبيوتر المحمول الخاص بك، أو لا ينتمي إلى أي مكان.
• النطاق. مع وصول الإرسال، يمكنك تقييد المفتاح بنطاق واحد تم التحقق منه. لا يمكن لمفتاح مقيد بنطاق notifications.example.com الإرسال من billing.example.com، مما يحد من نطاق تأثير التسريب.

يعرض Resend المفتاح مرة واحدة بالضبط. يبدأ بـ re_، وبمجرد إغلاق مربع الحوار، يمكنك إعادة تسمية المفتاح ولكن لا يمكنك رؤيته مرة أخرى أبدًا. انسخه مباشرة إلى متغير بيئة:

export RESEND_API_KEY="re_xxxxxxxxx"

إرشادات Resend الخاصة: لا تنتهي صلاحية المفاتيح أبدًا، لذا قم بتدويرها كل 90 يومًا أو قبل ذلك؛ تشير لوحة التحكم إلى أي مفتاح غير مستخدم لمدة 30 يومًا؛ وإذا تسرب مفتاح، فاحذفه فورًا بدلاً من انتظار الدورة التالية. يعد الالتزام بسلاسل re_ في Git هو المسار الأكثر شيوعًا للتسريب، لذا قم بتشغيل ماسح ضوئي سري على مستودعاتك قبل أول عملية دفع.

يمكنك أيضًا إنشاء مفاتيح باستخدام POST https://api.resend.com/api-keys، مع تمرير name، وpermission (full_access أو sending_access)، وdomain_id اختياري. يتطلب هذا الاستدعاء مفتاح وصول كامل، وهو سبب إضافي للاحتفاظ بمفتاح واحد فقط من هذا النوع.

الخطوة 4: إرسال بريدك الإلكتروني الأول

نقطة نهاية الإرسال هي POST https://api.resend.com/emails. المصادقة عبارة عن رمز Bearer في رأس Authorization، والجسم هو JSON، ويتم قبول HTTPS فقط. ثلاثة حقول مطلوبة: from، وto، وsubject. أضف html، أو text، أو كليهما؛ إذا أرسلت html فقط، فإن Resend ينشئ الجزء النصي العادي. يستقبل to سلسلة أو مصفوفة تصل إلى 50 عنوانًا. القائمة الكاملة للمعلمات موجودة في مرجع إرسال البريد الإلكتروني.

curl

curl -X POST 'https://api.resend.com/emails' \
  -H "Authorization: Bearer $RESEND_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "from": "Acme <onboarding@resend.dev>",
    "to": ["you@yourcompany.com"],
    "subject": "First Resend email",
    "html": "<p>Your Resend key works.</p>"
  }'

يعيد الاستدعاء الناجح {"id": "49a3999c-0ce1-4ea6-ab68-afcd6dc2e794"}. ملاحظة غريبة: يجب أن يحمل كل طلب رأس User-Agent، وإلا فإن واجهة برمجة التطبيقات (API) تجيب بـ 403 مع الرمز 1010. يقوم curl وحزم SDK بتعيين هذا الرأس؛ قد لا يقوم عميل مبرمج يدويًا في بيئة تشغيل حافة بذلك.

Node.js

npm install resend

import { Resend } from 'resend';

const resend = new Resend(process.env.RESEND_API_KEY);

const { data, error } = await resend.emails.send({
  from: 'Acme <notifications@example.com>',
  to: ['you@yourcompany.com'],
  subject: 'First Resend email',
  html: '<p>Your Resend key works.</p>',
});

if (error) {
  console.error(error);
} else {
  console.log(data.id);
}

لا يرمي Node SDK أبدًا أخطاء API. بل يعيد { data, error }، لذا تحقق من error قبل لمس data.id.

Python

pip install resend

import os
import resend
from resend.exceptions import ResendError

resend.api_key = os.environ["RESEND_API_KEY"]

params: resend.Emails.SendParams = {
    "from": "Acme <notifications@example.com>",
    "to": ["you@yourcompany.com"],
    "subject": "First Resend email",
    "html": "<p>Your Resend key works.</p>",
}

try:
    email = resend.Emails.send(params)
    print(email["id"])
except ResendError as err:
    print(err)

يقوم Python SDK بالعكس: فهو يرفع ResendError عند الفشل، لذا قم بتغليف عمليات الإرسال في try/except.

الخطوة 5: تخزين واختبار المفتاح في Apidog

يثبت Curl أن المفتاح يعمل مرة واحدة. Apidog يحول هذا الاستخدام لمرة واحدة إلى شيء يمكن لفريقك إعادة تشغيله، ويحتفظ بالمفتاح بعيدًا عن سجل الأوامر وسجلات الدردشة.

تخزين المفتاح كمتغير سري. أنشئ بيئة تسمى Resend، أضف RESEND_API_KEY كمتغير، وقم بتمييزه كسري حتى يتم إخفاء القيمة في واجهة المستخدم واستبعادها من التصدير. يغطي دليل البيئات والمتغيرات السرية تقسيمات التطوير، التجهيز، والإنتاج إذا كنت تحتفظ بمفتاح إرسال فقط مختلف لكل بيئة، وهو ما يجب عليك فعله.

إرسال الطلب. قم بإنشاء طلب POST إلى https://api.resend.com/emails، اضبط المصادقة على Bearer Token باستخدام {{RESEND_API_KEY}}، والصق جسم JSON من مثال curl. اضغط على إرسال. يظهر id في لوحة الاستجابة بجانب رؤوس تحديد المعدل الموضحة أدناه.

احفظه كاختبار. أضف تأكيدين: الحالة تساوي 200 و $.id موجود. ضع الطلب في سيناريو اختبار ولديك اختبار دخان يعمل كلما قام شخص ما بتعديل رمز البريد الإلكتروني. وجهه إلى بيئة الاختبار (staging) باستخدام مفتاح إرسال مقيد بالنطاق وهو آمن للتشغيل من CI.

محاكاة نقطة النهاية لعمل الواجهة الأمامية. تحتاج واجهتك الأمامية إلى شكل الاستجابة، وليس إرسالًا حقيقيًا. قم بمحاكاة نقطة النهاية في Apidog بحيث تُرجع {"id": "mock-email-id"} في كل استدعاء. يمكن لفريق واجهة المستخدم بناء حالة "البريد الإلكتروني المرسل" طوال اليوم دون المساس بحصتهم المجانية البالغة 100 رسالة يوميًا أو إرسال بريد مزعج إلى صندوق بريد حقيقي. قم بتنزيل Apidog لإعداد هذا؛ الخطة المجانية تغطي أربعة مستخدمين.

حدود الطبقة المجانية التي ستصادفها أولاً

تسرد صفحة تسعير Resend الخطة المجانية بـ 3000 رسالة بريد إلكتروني شهريًا، بحد أقصى 100 رسالة يوميًا، مع 3 نطاقات واحتفاظ بالبيانات لمدة 30 يومًا. تبدأ الخطة الاحترافية بسعر 20 دولارًا شهريًا مقابل 50000 رسالة بريد إلكتروني، و10 نطاقات، وبدون حد يومي، مع تجاوز الحد الأقصى بسعر 0.90 دولار لكل 1000 رسالة بريد إلكتروني.

تحتسب رسائل البريد الإلكتروني التجريبية المرسلة إلى عناوين resend.dev ضمن هذه الحصص، لذا فإن اختبار الحمل الذي يستهدف delivered@resend.dev لا يزال يستهلك 100 رسالة يوميًا. تحاكي bounced@resend.dev و complained@resend.dev و suppressed@resend.dev ارتدادًا صعبًا وشكوى بريد مزعج ومستلمًا محظورًا دون عناوين سيئة حقيقية.

بصرف النظر عن الحصة، يبلغ الحد الأقصى للمعدل الافتراضي 10 طلبات في الثانية لكل فريق، ويتم مشاركته عبر كل مفتاح في الفريق. يحمل كل رد رؤوس ratelimit-limit، وratelimit-remaining، وratelimit-reset، وretry-after، لذا يمكن لحلقة الإرسال التراجع قبل أن تصل إلى 429. هل تحتاج المزيد؟ يطلب منك Resend الاتصال بالدعم بدلاً من إنشاء فرق إضافية.

الأخطاء الشائعة وكيفية إصلاحها

يعود كل فشل كـ JSON مع statusCode، وname، وmessage. هذه هي الأخطاء التي ستواجهها في اليوم الأول، من مرجع الأخطاء:

عادة ما يعني الخطأ 401 مع مفتاح أنت متأكد من صحته وجود سطر جديد زائد في المتغير أو ملف .env لم يتم تحميله أبدًا. يبدو كلاهما وكأنه مفتاح مفقود من جانب واجهة برمجة التطبيقات.

الأسئلة الشائعة

هل يمكنني رؤية مفتاح Resend API الخاص بي مرة أخرى بعد إنشائه؟

لا. يعرض Resend القيمة مرة واحدة فقط وقت الإنشاء. إذا فقدته، أنشئ مفتاحًا جديدًا بنفس الاسم والإذن، ثم انشره، ثم احذف المفتاح القديم.

هل يجب أن أختار الوصول الكامل أو وصول الإرسال؟

وصول الإرسال، المقيد بنطاق واحد، لكل مفتاح يغادر جهازك. احتفظ بمفتاح وصول كامل واحد لعمليات نمط لوحة التحكم مثل إضافة النطاقات أو إنشاء مفاتيح أخرى، ولا تشحنه أبدًا في تطبيق.

هل يمكنني اختبار الإرسال دون التحقق من النطاق؟

نعم. استخدم onboarding@resend.dev كعنوان from وعنوان بريدك الإلكتروني الخاص كالمستلم. أي مستلم آخر يعيد 403 حتى يتم التحقق من النطاق.

هل هناك طريقة لإدارة Resend من الطرفية بدلاً من لوحة التحكم؟

نعم. يغطي دليل Resend CLI تثبيته وتشغيل أوامر النطاق والبريد الإلكتروني الشائعة دون فتح متصفح.

ماذا يحدث عندما أتجاوز 100 رسالة بريد إلكتروني في اليوم على الخطة المجانية؟

تعيد واجهة برمجة التطبيقات (API) الخطأ 429 مع daily_quota_exceeded، وتستأنف الإرسالات بعد إعادة التعيين اليومية. إذا كنت تحتاج المزيد بانتظام، فإن خطة Pro تزيل الحد الأقصى، ويعرض ملخص واجهات برمجة تطبيقات البريد الإلكتروني المجانية كيف تتشابه مستويات الخدمة المجانية لمقدمي الخدمات الآخرين.

الخلاصة

الحصول على مفتاح Resend API يستغرق دقيقتين؛ الحصول عليه بشكل صحيح يستغرق خمسة. تحقق من نطاق فرعي، أنشئ مفتاحًا مخصصًا للإرسال فقط ومقيدًا بهذا النطاق، احتفظ به في متغير بيئة، وأرسل بريدًا إلكترونيًا واحدًا باستخدام curl لتأكيد العملية الكاملة. ثم انقل الطلب إلى Apidog، احفظ التأكيدات، وحاكي نقطة النهاية حتى يتمكن بقية فريقك من البناء عليها دون استهلاك حصتك. شحن أقل مفتاح قوة لا يزال يؤدي المهمة.