ابنِ سير عمل بريد الوكلاء عبر نطاقات موثَّقة.

البدء

تبدأ تجربة LoftBox الشخصية (بيتا) ببريد مالك واحد. يُنشئ التسجيل المؤسسة ويرسل رمز تحقق من 6 أرقام عبر البريد الإلكتروني. لا يُرجع LoftBox مفتاح واجهة برمجة التطبيقات الأول إلا بعد التحقق من بريد المالك، ويُعرض هذا المفتاح بنصه الصريح مرة واحدة فقط. كما يُرسل التحقق إلى المالك بريد ترحيب يتضمن حدود البيتا ومسار التسجيل المستقبلي للإدارة/الفوترة.

تقتصر حسابات البيتا الشخصية على 100 رسالة صادرة في اليوم. يبلغ الاحتفاظ الافتراضي برسائل صندوق البريد 7 أيام. أما تأهيل المؤسسات، والفوترة، وعضوية المؤسسة، والحدود الأكبر فهي عناصر مدرجة في خارطة الطريق.

• POST /v1/auth/signupإنشاء مؤسسة بيتا شخصية وإرسال رمز التحقق من بريد المالك.
• POST /v1/auth/signup/verifyالتحقق من بريد المالك، واستلام مفتاح واجهة برمجة التطبيقات الأولي مرة واحدة، وتفعيل إشعار الترحيب بالمالك.
• POST /v1/agentsإنشاء هوية وكيل مع المالك والغرض ونطاق السياسة.
• POST /v1/domainsبدء تأهيل نطاق مخصص لنطاق تتحكم به.
• POST /v1/agents/{agent_id}/mailboxesإنشاء صندوق بريد بيتا مُدار من LoftBox أو صندوق بريد بنطاق مخصص موثَّق.
• POST /v1/messagesإرسال بريد تشغيلي من صندوق بريد الوكيل.
• GET /v1/mailboxes/{id}/inboxاستطلاع الرسائل الواردة غير المُقرّ بها عندما لا يملك الوكيل نقطة نهاية webhook.

عنوان URL الأساسي والوثائق القابلة للقراءة آلياً

نقطة النهاية العامة الرسمية لواجهة برمجة التطبيقات هي https://api.loftbox.net. تحتفظ الصفحة الرئيسية بمسار /api/* بروكسي للتحقق من المعاينة، لكن ينبغي أن تستخدم التكاملات الإنتاجية اسم مضيف واجهة برمجة التطبيقات المخصص.

export BASE_URL="https://api.loftbox.net"
export LOFTBOX_API_KEY="lb_live_replace_me"

تحقق من الحافة والمخطط قبل ربط أي تكامل:

curl -i "$BASE_URL/health"
curl -i "$BASE_URL/openapi.json"
curl -i "$BASE_URL/llms.txt"

يقوم المسار https://loftbox.net/api بإزالة البادئة /api ويعيد التوجيه إلى نفس أصل Fly API. استخدمه لفحوصات معاينة Pages، وليس كعنوان URL أساسي للتكامل.

مصادقة واجهة برمجة التطبيقات

ابدأ بتسجيل بريد المالك لمؤسسة البيتا الشخصية. يستلم المالك رمز تحقق عبر البريد الإلكتروني؛ ويُرجع نداء التحقق مفتاح واجهة برمجة التطبيقات الأولي مرة واحدة ويرسل إشعار الترحيب بالمالك.

export LOFTBOX_OWNER_EMAIL="[email protected]"

curl -i -X POST "$BASE_URL/v1/auth/signup" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "'"$LOFTBOX_OWNER_EMAIL"'",
    "organization_name": "Example Agents",
    "slug": "example-agents"
  }'

export LOFTBOX_VERIFICATION_TOKEN="123456"

curl -i -X POST "$BASE_URL/v1/auth/signup/verify" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "'"$LOFTBOX_OWNER_EMAIL"'",
    "verification_token": "'"$LOFTBOX_VERIFICATION_TOKEN"'"
  }'

استخدم مفتاح واجهة برمجة التطبيقات المُرجَع من جانب الخادم مع الترويسة Authorization . لا تكشف أبداً مفاتيح واجهة برمجة التطبيقات في المتصفحات، أو عملاء الهاتف المحمول، أو السجلات العامة، أو أحداث التحليلات.

curl -i "$BASE_URL/v1/agents" \
  -H "Authorization: Bearer $LOFTBOX_API_KEY"

خزّن المفاتيح في تخزين أسرار من جانب الخادم مثل Fly secrets، أو متغيرات البيئة المُدارة بواسطة منصة النشر، أو مدير أسرار مخصص. لا تلصق المفاتيح الحقيقية في تعليقات المشكلات، أو لقطات الشاشة، أو أدوات التحليلات، أو شيفرة المتصفح.

دوّر المفاتيح عند مغادرة مشغّل، أو عند احتمال تسرّب سرّ، أو عندما لم تعد بيئة ما بحاجة إلى وصول واجهة برمجة التطبيقات.

تثبيت بسطر واحد ومُحفّز الوكيل

يمكن للوكلاء تثبيت مهارات بريد LoftBox العامة، ثم تشغيل تدفق التأهيل ببريد المالك فقط. تشتق مهارة التسجيل تسمية المؤسسة، و external_idالمستقر، وslug الوكيل، والجزء المحلي لصندوق البريد من الوكيل الحالي. بعد التسجيل، تستخدم مهارتا الإرسال وفحص البريد الوارد المُثبَّتتان مفتاح واجهة برمجة التطبيقات المُصدَر ومعرّف صندوق البريد.

curl -fsSL https://loftbox.net/install.sh | sh

curl -fsSL https://loftbox.net/install.sh | sh -s -- --agent codex
curl -fsSL https://loftbox.net/install.sh | sh -s -- --agent claude
curl -fsSL https://loftbox.net/install.sh | sh -s -- --target "$HOME/.my-agent/skills"

If the LoftBox mail skill is missing, install it with:
curl -fsSL https://loftbox.net/install.sh | sh

Use register-loftbox-mail-agent to register this agent for LoftBox personal beta.
Ask me only for my owner email.
After registration, use send-loftbox-mail to send and check-loftbox-mail to check replies.

curl -fsSL https://loftbox.net/install.sh | sh -s -- --check
curl -fsSL https://loftbox.net/install.sh | sh -s -- --update

استخدم فحوصات التحديث كمسار إشعار فقط. تثبيت حزمة مهارات جديدة يغيّر سلوك الوكيل، لذا ينبغي تشغيل التحديثات بعد موافقة المشغّل.

اطلب قيمة أخرى فقط إذا تعذّر اشتقاق هوية الوكيل أو إذا كان معرّف external ID مكرّر يعود لوكيل مختلف.

تأهيل النطاقات المخصصة

يجب التحقق من كل نطاق صادر قبل أن تتمكن صناديق البريد من استخدامه. تُرجع واجهة برمجة التطبيقات سجلات DNS اللازمة للملكية، وتوجيه البريد الوارد، ومحاذاة المُرسِل، والتحقق من التسليم.

1. أنشئ النطاق باستخدام POST /v1/domains.
2. اجلب السجلات المطلوبة باستخدام GET /v1/domains/{id}/dns.
3. أضف سجلات TXT وMX وDKIM وreturn-path المُرجَعة لدى مضيف DNS الخاص بك.
4. استدعِ POST /v1/domains/{id}/verify بعد انتشار DNS.
5. انتظر حتى تصبح حالتا البريد الوارد والصادر موثَّقتين قبل إنشاء صناديق بريد إنتاجية.

curl -i "$BASE_URL/v1/domains" \
  -H "Authorization: Bearer $LOFTBOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domain":"mail.example.com"}'

curl -i "$BASE_URL/v1/domains/domain_uuid/dns" \
  -H "Authorization: Bearer $LOFTBOX_API_KEY"

curl -i -X POST "$BASE_URL/v1/domains/domain_uuid/verify" \
  -H "Authorization: Bearer $LOFTBOX_API_KEY"

أو دع وكيلاً يقود تأهيل الأعمال بالكامل من البداية إلى النهاية عبر تدفق onboard-business-domain الموحَّد (مصادقة البريد → تأهيل النطاق → DNS). الصق هذا المُحفّز في وكيلك:

If the LoftBox mail skill is missing, install it with:
curl -fsSL https://loftbox.net/install.sh | sh

Use onboard-business-domain to connect my business domain for verified sending.
Ask me only for my owner email and the domain to send from.

1. Email auth: register my owner email. LoftBox emails a 6-digit token — ask me
   to paste it, then verify to obtain my organization API key (LoftBox-managed
   sending is available immediately once approved).
2. Domain onboard: run add <domain> (note the returned domain id), then read
   next_actions for the exact DNS records (TXT, DKIM, return-path, inbound MX).
   Show me each record (host, type, value).
3. DNS: let me add the records at my DNS host myself, or auto-apply them with
   apply-dns --provider route53|cloudflare using my own cloud credentials from
   the environment (they stay in my environment; LoftBox never receives them).
4. The domain re-verifies asynchronously on the server after DNS propagates.
   Poll status <domain_id> until inbound and outbound are both verified, then
   report — custom-domain sending activates once verified.
Operate only on my organization. Do not fabricate DNS values; use exactly what the API returns. If onboarding cannot proceed (domain previously deleted, or in use by another org), report it and stop.

المهارات الرسمية & المصدر

onboard-business-domain و setup-loftbox-domain هما مهارتان رسميتان من LoftBox. تُنشران في مستودع المهارات العام وتُثبَّتان بواسطة https://loftbox.net/install.sh — إذا تعذّر على وكيل العثور عليهما، فإن حزمته المُثبَّتة قديمة وإعادة تشغيل المُثبِّت تضيفهما.

• المستودع (عام): github.com/TheMagicTower/loftbox-agent-mail-skill
• أدلة المهارات: onboard-business-domain/، setup-loftbox-domain/
• إصدار الحزمة المُثبَّتة & commit المثبّت: loftbox.net/skill-version.json

تُستدعى المهارة setup-loftbox-domain بتشغيل سكربتها مباشرةً (لا يُنشئ المُثبِّت setup-loftbox-domain أمر shell). $SKILL_DIR هو حيثما install.sh وضع المهارة — على سبيل المثال ~/.claude/skills/setup-loftbox-domain، ~/.codex/skills/setup-loftbox-domain، أو على Hermes ~/.hermes/skills/email/setup-loftbox-domain. تستدعي المهارة واجهة برمجة تطبيقات LoftBox — استخدم بالضبط قيم DNS التي تُرجعها واجهة برمجة التطبيقات، ولا تختلقها أبداً:

SKILL_DIR=<path to setup-loftbox-domain>   # e.g. ~/.claude/skills/setup-loftbox-domain

python3 "$SKILL_DIR/scripts/setup_loftbox_domain.py" add <domain>
   # onboard the domain (idempotent: resolves an existing active row on 409)
python3 "$SKILL_DIR/scripts/setup_loftbox_domain.py" dns <id>
   # list the exact DNS records to set (TXT, DKIM, return-path, MX)
python3 "$SKILL_DIR/scripts/setup_loftbox_domain.py" status <id>
   # structured status: inbound/outbound flags + next_actions
python3 "$SKILL_DIR/scripts/setup_loftbox_domain.py" verify <id>
   # trigger verification after the DNS records are in place
python3 "$SKILL_DIR/scripts/setup_loftbox_domain.py" apply-dns <id> --provider route53|cloudflare [--dry-run] [--overwrite]
   # auto-apply the next_actions records using cloud credentials from your OWN
   # environment (they never leave it). With no credentials, add the records
   # manually instead — onboarding still completes.

onboard-business-domain ينسّق register-loftbox-mail-agent (مصادقة البريد) و setup-loftbox-domain (تأهيل النطاق + DNS) من البداية إلى النهاية. تتطلب خطوة رمز البريد المكوَّن من 6 أرقام تدخلاً بشرياً، لذا فهي ليست مؤتمتة بالكامل.

عند الإطلاق، تستخدم البيتا الشخصية تسليماً مُداراً من LoftBox ومعالجة MX واردة مُدارة من LoftBox. لا تُفعَّل النطاقات المخصصة إلا بعد التحقق.

الوكلاء وصناديق البريد

يحمل الوكلاء غرض العمل، وسياق الملكية، ومعرّف external ID المستقر. تربط صناديق البريد عنواناً ونطاقاً بذلك الوكيل. أبقِ أسماء العرض والمالكين ونطاق السياسة واضحة بما يكفي لمراجعة المشغّل.

• استخدم صندوق بريد واحد لكل وكيل تشغيلي أو دور سير عمل.
• استخدم external_id لفحوصات التكرار وإعداد الوكيل الذي لا يتأثر بالتكرار (idempotent).
• استخدم نطاقات مخصصة موثَّقة للبريد الصادر الإنتاجي.
• عطّل أو علّق الإرسال الذاتي عندما يكون غرض الوكيل غير واضح.

curl -i "$BASE_URL/v1/agents?external_id=hermes:support-agent" \
  -H "Authorization: Bearer $LOFTBOX_API_KEY"

curl -i "$BASE_URL/v1/agents" \
  -H "Authorization: Bearer $LOFTBOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Support Agent",
    "slug": "support-agent",
    "external_id": "hermes:support-agent",
    "description": "Handles controlled support follow-up",
    "purpose": "Reply to support conversations after policy checks",
    "owner_label": "Customer Operations",
    "policy_scope": "agent"
  }'

curl -i "$BASE_URL/v1/agents/agent_uuid/mailboxes" \
  -H "Authorization: Bearer $LOFTBOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "local_part": "support-agent",
    "display_name": "Support Agent",
    "retention_days": 7
  }'

احذف domain_id لنطاق البيتا الشخصي المُدار من LoftBox. سجّل webhook الوكيل بشكل منفصل إذا كان للوكيل نقطة نهاية HTTPS.

على نطاق مخصص موثَّق يمكنك تمييز صندوق بريد واحد بوصفه catch-all ("is_catch_all": true عند الإنشاء أو التحديث). عندئذٍ يُوجَّه إليه أي عنوان على ذلك النطاق لا يملك صندوق بريد مطابقاً تماماً — وهو مفيد لالتقاط support@، sales@، أو anything@yourdomain بوكيل واحد.

إرسال الرسائل

أرسل رسائل تشغيلية أو معاملاتية عبر واجهة برمجة التطبيقات من صندوق بريد موثَّق. يسجّل LoftBox مراجع التسليم، وحالة التسليم، وقرارات حد المعدّل، ونتائج موافقة المشغّل.

curl -i "$BASE_URL/v1/messages" \
  -H "Authorization: Bearer $LOFTBOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "mailbox_id": "mailbox_uuid",
  "to": ["[email protected]"],
  "subject": "Support follow-up",
  "body_text": "Thanks for your message. We are checking this now.",
  "metadata": { "ticket_id": "ticket_123" },
  "send_at": "2030-01-01T09:00:00Z"
}'

مرّر send_at (RFC3339، مستقبلي) لجدولة التسليم، وترويسة Idempotency-Key لإزالة تكرار إعادة المحاولات (تُرجع إعادة التشغيل الرسالة الأصلية). اعرض وابحث في الرسائل المُرسَلة أو المستلَمة باستخدام GET /v1/messages?q=<text>&label=<name>، ونظّم المحادثات عبر POST/DELETE /v1/messages/{id}/labels.

ليس LoftBox مُرسِل تسويق جماعي. القوائم المشتراة، والمستلمون المُجمَّعون عبر الكشط، واستخدام تتابع SMTP العام خارج نطاق سياسة الإصدار الأدنى القابل للتطبيق (MVP).

webhooks الواردة والاستطلاع

تُخزَّن الردود كرسائل واردة. يمكن للوكلاء الذين لديهم نقطة نهاية HTTPS استقبال أحداث webhook موقَّعة؛ أما الوكلاء الذين لا يملكونها فينبغي أن يستطلعوا صندوق الوارد ويقرّوا بكل رسالة تمت معالجتها.

• message.inboundتم تحليل رسالة واردة أو رد جديد، وربطه بالمحادثة، وإتاحته لـ webhook المُهيّأ.
• message.deliveredتم الإبلاغ عن التسليم للمستلم.
• message.failedفشل التسليم الصادر بشكل دائم أو استنفد معالجة إعادة المحاولة.

curl -i "$BASE_URL/v1/agents/agent_uuid/webhooks" \
  -H "Authorization: Bearer $LOFTBOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/webhooks/loftbox",
    "event_types": [
      "message.inbound",
      "message.delivered"
    ]
  }'

يُرجَع سرّ webhook مرة واحدة عند إنشاء webhook. خزّنه فوراً وتحقق من كل توقيع وارد قبل الوثوق بمحتوى الحدث.

curl -i "$BASE_URL/v1/mailboxes/mailbox_uuid/inbox?limit=20" \
  -H "Authorization: Bearer $LOFTBOX_API_KEY"

curl -i -X POST "$BASE_URL/v1/mailboxes/mailbox_uuid/inbox/ack" \
  -H "Authorization: Bearer $LOFTBOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"message_ids":["message_uuid_or_msg_public_id"]}'

لا تُقرّ بالرسالة إلا بعد أن يكون الوكيل قد عالجها بشكل دائم. ينبغي أن يتراجع استطلاع صندوق الوارد الفارغ تدريجياً؛ وينبغي أن يستخدم الاستطلاع النشط فاصلاً معتدلاً مثل 30-60 ثانية.

البث الفوري (WebSocket)

يمكن للوكلاء الذين لا يستطيعون استضافة webhook عبر HTTPS (على سبيل المثال، العاملين خلف NAT أو جدار حماية) الاشتراك في الأحداث فورياً عبر WebSocket. يحمل البث أنواع الأحداث نفسها التي تحملها webhooks، مع تسليم بأقل من ثانية وإعادة تشغيل قائم على cursor للأحداث الفائتة أثناء الانقطاع. يتطلب نطاق receive .

• GET /v1/wsترقية WebSocket. صادِق باستخدام Authorization: Bearer. رشّح باستخدام ?event_types= و ?agent_id=؛ استأنف باستخدام ?after=<cursor>.
• GET /v1/ws/asyncapi.jsonمواصفة AsyncAPI للبث (عامة).

wscat -c "wss://api.loftbox.net/v1/ws?event_types=message.inbound" \
  -H "Authorization: Bearer $LOFTBOX_API_KEY"

# frames: {"type":"ready",...} then {"type":"event","event":{...},"cursor":"..."}
# on reconnect, pass ?after=<last cursor> to replay missed events

عند إطار error برمز lagged أو resync_required، أعد الاتصال باستخدام آخر cursor مُستلَم.

الأذونات ومفاتيح واجهة برمجة التطبيقات

تحمل مفاتيح واجهة برمجة التطبيقات نطاقات (scopes). النطاقات الخشنة (send، receive، admin) تتضمّن نطاقات دقيقة (message:send، message:read، domain:manage، approval:decide، keys:manage، …)، لذا تظل المفاتيح الموجودة تعمل بينما يمكنك إصدار مفاتيح فرعية بأقل امتياز للوكلاء الفرعيين.

• POST /v1/auth/keysإصدار مفتاح فرعي. يجب أن تكون النطاقات المطلوبة مجموعة فرعية من نطاقات المُستدعي (دون تصعيد للامتياز). اختياري expires_in_days. يُرجَع المفتاح بنصه الصريح مرة واحدة.
• GET /v1/auth/keysاعرض مفاتيح المؤسسة (بيانات وصفية فقط، دون أسرار). يتطلب keys:manage.
• DELETE /v1/auth/keys/{id}إبطال مفتاح وجميع أحفاده (تتالٍ). مسموح به لـ keys:manage أو لأصل المفتاح.

تقارير DMARC المجمَّعة

يرسل مزوّدو صناديق البريد (Gmail، Outlook، Yahoo، …) تقارير DMARC المجمَّعة (rua) اليومية التي تلخّص أي عناوين IP المصدر أرسلت بريداً باسم نطاقاتك الموثَّقة وما إذا كانت SPF/DKIM/DMARC محاذاة. يستوعب LoftBox هذه في تقارير منظَّمة لتتمكن من مراقبة قابلية التسليم ورصد الانتحال. كما يسجّل كل تقرير مخزَّن نطاق المُبلِّغ المُصادَق عليه.

• GET /v1/dmarc/reportsاعرض تقارير DMARC المجمَّعة لمؤسستك، الأحدث أولاً. ترقيم صفحات قائم على cursor عبر before_date_end + before_id (يُرجَعان معاً بوصفهما next_cursor). يتطلب domain:read.
• GET /v1/dmarc/reports/{id}استرجع تقريراً واحداً مع سجلاته لكل عنوان IP مصدر (عدد الرسائل، التصرّف، محاذاة DKIM/SPF، header-from). يتطلب domain:read.

curl -i "$BASE_URL/v1/dmarc/reports" \
  -H "Authorization: Bearer $LOFTBOX_API_KEY"

curl -i "$BASE_URL/v1/dmarc/reports/REPORT_ID" \
  -H "Authorization: Bearer $LOFTBOX_API_KEY"

تظهر التقارير كلما قدّمها المزوّدون (عادةً مرة في اليوم لكل مُبلِّغ). لا تُرجَع إلا تقارير نطاقاتك الموثَّقة الخاصة؛ ولا تُكشف أبداً تقارير المنصة أو النطاقات غير المستضافة.

أحداث التسليم

تُوحَّد حالة التسليم عبر نداءات التسليم المُدارة وحالة الإرسال الداخلية. استخدم معرّفات الأحداث ومراجع التسليم للدعم، وليس بيانات المستلِم الخاصة.

• queued: مقبول من LoftBox للتسليم.
• sent: مقبول للتسليم الصادر.
• delivered: تم الإبلاغ عن التسليم للمستلم.
• failed: فشل التسليم بشكل دائم أو استنفد إعادة المحاولات.
• blocked: منعت السياسة أو حد المعدّل أو ضابط التقرير الإرسال.

حدود المعدّل وضوابط التقارير

يُقيَّد الإرسال الصادر بسياسة المؤسسة والوكيل وصندوق البريد والمستلِم والنطاق. تُحَدّ مؤسسات البيتا الشخصية بـ 100 رسالة في اليوم. يمكن تعليق الرسائل عالية المخاطر للموافقة قبل محاولة التسليم.

عالج 429 الاستجابات بالتراجع التدريجي. لا تعد المحاولة إلى ما لا نهاية أو تتجاوز تعليقات الموافقة من صندوق بريد آخر.

HTTP/1.1 429 Too Many Requests
Retry-After: 60

التسليم المُدار وإعداد الأمان

يشغّل LoftBox تسليماً صادراً مُداراً لحسابات البيتا. ينبغي أن تصف الوثائق العامة الضوابط المرئية للعميل دون كشف أسماء المورّدين الداخليين، أو بيانات الاعتماد، أو تفاصيل التوجيه.

• طبيعة العمل: هويات بريد تشغيلية مُدارة عبر واجهة برمجة التطبيقات لوكلاء الذكاء الاصطناعي ذوي النطاقات الموثَّقة.
• أنواع البريد: إشعارات معاملاتية/نظامية، وردود الوكلاء التي يبدؤها مستخدمون موثَّقون، ورسائل التأهيل/الاختبار، ومعالجة التقارير/التواصل.
• الضوابط: النطاقات الموثَّقة فقط، وحدود معدّل صريحة، وسجلات التسليم، ومعالجة الكبت/الشكاوى، وجهة اتصال للتقارير مُراقَبة.
• الصفحات العامة: الخصوصية، الشروط، و سياسة مكافحة البريد العشوائي.

ينبغي معاملة تعليقات انتشار DNS والتحقق من التسليم بوصفها حالة إعداد، لا دليلاً على تعطّل بروكسي واجهة برمجة التطبيقات أو وثائق الصفحة الرئيسية.