API بريد مؤقت وخادم MCP للاختبارات ولوكلاء الذكاء الاصطناعي

بدء سريع باستخدام curl

أنشئ صندوقًا، وانتظر الرسالة التالية، واقرأها، ثم احذف الصندوق. احفظ مفتاح API في TEMPGENERATOR_TOKEN ولا تضعه أبدًا في عنوان URL.

يتطلب curl وjq. ينتظر السكربت حتى ثلاث مرات، 20 ثانية في كل مرة، ويعرض موضوع كل رسالة ورموزها وروابطها ونصها، ثم يحذف الصندوق.

export TEMPGENERATOR_URL='https://www.tempgenerator.com'
API="$TEMPGENERATOR_URL/developer-api/v1"
AUTH="Authorization: Bearer $TEMPGENERATOR_TOKEN"
INBOX=$(curl --fail-with-body -sS -X POST "$API/inboxes" -H "$AUTH" -H 'Accept: application/json')
ID=$(printf '%s' "$INBOX" | jq -r .id)
echo "Send a test email to $(printf '%s' "$INBOX" | jq -r .address)"
for ATTEMPT in 1 2 3; do
  RESULT=$(curl --fail-with-body -sS "$API/inboxes/$ID/wait?after=0&timeout=20" -H "$AUTH" -H 'Accept: application/json')
  [ "$(printf '%s' "$RESULT" | jq -r .status)" = message ] && break
done
for MESSAGE in $(printf '%s' "$RESULT" | jq -r '.messages[].id'); do
  curl --fail-with-body -sS "$API/inboxes/$ID/messages/$MESSAGE" -H "$AUTH" -H 'Accept: application/json' \
    | jq '{subject, codes, links, text}'
done
curl --fail-with-body -sS -X DELETE "$API/inboxes/$ID" -H "$AUTH"

نظرة سريعة على API

عنوان URL الأساسي: https://www.tempgenerator.com/developer-api/v1. أرسل Authorization: Bearer <key> مع كل طلب. الاستجابات بتنسيق JSON، والأخطاء بالشكل {"error": {"code", "message", "retry_after"}}، وترسل أخطاء الحصة أيضًا ترويسة Retry-After.

• POST /inboxes إنشاء صندوق والحصول على عنوانه وموعد انتهاء صلاحيته
• GET /inboxes/{id}/wait?after=0&timeout=20 انتظار الرسالة التالية بعد مؤشر لمدة أقصاها 20 ثانية
• GET /inboxes/{id}/messages?after=0 عرض ما يصل إلى 50 رسالة بعد مؤشر، من الأقدم إلى الأحدث
• GET /inboxes/{id}/messages/{message_id} قراءة رسالة واحدة: النص والرموز والروابط وقائمة المرفقات
• GET /inboxes/{id}/messages/{message_id}/attachments/{index} تنزيل مرفق واحد حسب فهرسه
• DELETE /inboxes/{id} حذف الصندوق ورسائله فورًا

تقبل نقطتا العرض والانتظار عاملي التصفية الاختياريين from وsubject_contains، وهما يطابقان المرسل والموضوع بشرط «يحتوي على» دون تمييز بين الأحرف الكبيرة والصغيرة.

مثال على استجابة القراءة

{
    "id": 42,
    "from": "no-reply@app.example",
    "subject": "Your verification code",
    "received_at": "2026-10-03T09:41:07+00:00",
    "text": "Your verification code is 482913.\nOr confirm: https://app.example/verify?token=8f3c",
    "text_truncated": false,
    "codes": [
        "482913"
    ],
    "links": [
        "https://app.example/verify?token=8f3c"
    ],
    "expires_at": "2026-10-03T10:40:12+00:00",
    "attachments": [
        {
            "index": 0,
            "filename": "receipt.pdf",
            "size": 48213
        }
    ],
    "untrusted_content": true
}

الرموز المميزة للمطوّرين

أنشئ مفاتيح API من صفحة «وصول المطوّر» بعد تأكيد بريدك الإلكتروني. يستطيع مفتاح القراءة والكتابة إنشاء الصناديق وقراءتها وحذفها، ويستطيع مفتاح القراءة فقط العرض والانتظار والقراءة والتنزيل. تنتهي صلاحية المفاتيح بعد 90 يومًا، ويمكن أن يملك الحساب حتى 10 مفاتيح نشطة، ويسري إلغاء المفتاح فورًا.

يُعرض كل مفتاح مرة واحدة ولا يُخزَّن إلا بصيغة تجزئة SHA-256. لا يحذف إلغاء المفتاح صناديقه: تحتفظ مفاتيح الحساب الصالحة الأخرى بالوصول إليها حتى تنتهي صلاحيتها أو تُحذف.

انتظار الرسالة التالية دون sleep()

يُبقي GET …/wait الطلب مفتوحًا ويعيد الاستجابة فور وصول رسالة، أو بعد انتهاء المهلة (20 ثانية كحد أقصى) مع status timeout. مرّر next_cursor من الاستجابة السابقة كقيمة لـ after حتى لا تقرأ الرسالة نفسها مرتين.

انتهاء المهلة ليس فشلًا في التسليم: انتظر مجددًا بالمؤشر نفسه. يعمل انتظار واحد لكل صندوق، ويحل الانتظار الأحدث على الصندوق نفسه محل الأقدم، أما عمليات الانتظار على صناديق مختلفة فتعمل بالتوازي، بحد أقصى 2 في آن واحد لكل حساب.

اختبار البريد الإلكتروني في Playwright وCypress وpytest وCI

خصّص لكل اختبار صندوقًا مستقلًا، واجعل تطبيقك يرسل رسالة التسجيل أو إعادة تعيين كلمة المرور، ثم انتظرها وتحقّق من الرمز أو الرابط. احذف الصندوق في مرحلة التنظيف (teardown).

خزّن المفتاح كسرّ في CI، مثل TEMPGENERATOR_TOKEN في GitHub Actions. يستطيع Cypress إجراء استدعاءات HTTP نفسها عبر cy.request، وتعمل وصفة Python أدناه مع pytest أو أي مشغّل اختبارات آخر.

Playwright (TypeScript)

import { test, expect } from '@playwright/test';

const api = `${process.env.TEMPGENERATOR_URL}/developer-api/v1`;
const headers = { Authorization: `Bearer ${process.env.TEMPGENERATOR_TOKEN}`, Accept: 'application/json' };

async function call(path: string, method = 'GET') {
  const response = await fetch(api + path, { method, headers });
  if (!response.ok) throw new Error(`${response.status} ${await response.text()}`);
  return response.status === 204 ? null : response.json();
}

async function waitForCode(inboxId: string, after = 0): Promise<string> {
  for (let attempt = 0; attempt < 3; attempt++) {
    const result = await call(`/inboxes/${inboxId}/wait?after=${after}&timeout=20`);
    for (const summary of result.messages) {
      const message = await call(`/inboxes/${inboxId}/messages/${summary.id}`);
      if (message.codes.length) return message.codes[0];
    }
    after = result.next_cursor;
  }
  throw new Error('No verification code arrived');
}

test('signup sends a verification code', async ({ page }) => {
  const inbox = await call('/inboxes', 'POST');
  try {
    await page.goto('/signup');
    await page.getByLabel('Email').fill(inbox.address);
    await page.getByRole('button', { name: 'Create account' }).click();
    await page.getByLabel('Verification code').fill(await waitForCode(inbox.id));
    await expect(page.getByText('Welcome')).toBeVisible();
  } finally {
    await call(`/inboxes/${inbox.id}`, 'DELETE');
  }
});

GitHub Actions

- name: End-to-end tests
  run: npx playwright test
  env:
    TEMPGENERATOR_URL: https://www.tempgenerator.com
    TEMPGENERATOR_TOKEN: ${{ secrets.TEMPGENERATOR_TOKEN }}

فحص التسجيل باستخدام Python

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

import json, os
from urllib.request import Request, urlopen

base = os.environ["TEMPGENERATOR_URL"].rstrip("/") + "/developer-api/v1"
headers = {"Authorization": "Bearer " + os.environ["TEMPGENERATOR_TOKEN"],
           "Accept": "application/json"}

def request(path, method="GET"):
    with urlopen(Request(base + path, headers=headers, method=method), timeout=30) as response:
        return json.load(response) if response.status != 204 else None

inbox = request("/inboxes", "POST")
print(json.dumps(inbox), flush=True)
try:
    input()
    result = request("/inboxes/" + inbox["id"] + "/wait?after=0&timeout=15")
    print(json.dumps(result))
    for message in result["messages"]:
        detail = request("/inboxes/" + inbox["id"] + "/messages/" + str(message["id"]))
        print(json.dumps(detail))
finally:
    request("/inboxes/" + inbox["id"], "DELETE")

خادم MCP لوكلاء الذكاء الاصطناعي

نقطة النهاية https://www.tempgenerator.com/mcp، والمصادقة عبر Authorization: Bearer <key>. نقل Streamable HTTP بالبروتوكول 2026-07-28، ويُخدَم العملاء الأقدم عبر المصافحة 2025-11-25 أو 2025-06-18.

ربط العميل

Claude Code

claude mcp add --transport http tempgenerator-mail https://www.tempgenerator.com/mcp \
  --header "Authorization: Bearer $TEMPGENERATOR_TOKEN"

Cursor: .cursor/mcp.json

{
  "mcpServers": {
    "tempgenerator-mail": {
      "url": "https://www.tempgenerator.com/mcp",
      "headers": { "Authorization": "Bearer ${env:TEMPGENERATOR_TOKEN}" }
    }
  }
}

VS Code: .vscode/mcp.json

{
  "inputs": [
    { "type": "promptString", "id": "tempgenerator-token", "description": "TempGenerator API key", "password": true }
  ],
  "servers": {
    "tempgenerator-mail": {
      "type": "http",
      "url": "https://www.tempgenerator.com/mcp",
      "headers": { "Authorization": "Bearer ${input:tempgenerator-token}" }
    }
  }
}

Claude على الويب وتطبيق سطح المكتب: أضف موصلًا مخصصًا بعنوان URL لنقطة النهاية، واختر عدم تسجيل الدخول، ثم أضف ترويسة الطلب Authorization: Bearer <key>. يتصل Claude من سحابة Anthropic، لذا يجب أن يكون عنوان URL متاحًا للعموم.

الأدوات

create_inbox

ينشئ صندوقًا خاصًا ويعيد معرّفه وعنوانه.

list_messages

يعرض ملخصات الرسائل بعد مؤشر، مع عاملي تصفية اختياريين للمرسل والموضوع.

wait_for_message

ينتظر الرسالة التالية لمدة أقصاها 20 ثانية.

read_message

يقرأ نص رسالة واحدة ورموزها وروابطها وقائمة مرفقاتها.

delete_inbox

يحذف الصندوق ورسائله.

مثال على موجّه

أنشئ صندوقًا مؤقتًا وأعطني عنوانه. ثم انتظر رسالة التحقق من تطبيقي في بيئة staging وأخبرني بالرمز.

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

MCP SDK للغة Python

تم اختباره مع Python 3 وحزمة mcp الرسمية 2.3.0: pip install "mcp>=2.3,<3". اضبط TEMPGENERATOR_URL وTEMPGENERATOR_TOKEN أولًا.

import asyncio, os

import httpx2
from mcp import Client
from mcp.client.streamable_http import streamable_http_client

async def main():
    url = os.environ["TEMPGENERATOR_URL"].rstrip("/") + "/mcp"
    headers = {"Authorization": "Bearer " + os.environ["TEMPGENERATOR_TOKEN"]}
    async with httpx2.AsyncClient(headers=headers, timeout=httpx2.Timeout(30, read=60)) as http:
        async with Client(streamable_http_client(url, http_client=http)) as client:
            print([tool.name for tool in (await client.list_tools()).tools])
            created = await client.call_tool("create_inbox", {})
            if created.is_error:
                raise RuntimeError(created.content)
            inbox = created.structured_content
            try:
                print("Send a test email to", inbox["address"])
                waited = await client.call_tool("wait_for_message", {"inbox_id": inbox["id"], "timeout": 20})
                for summary in waited.structured_content["messages"]:
                    message = await client.call_tool("read_message", {"inbox_id": inbox["id"], "message_id": summary["id"]})
                    print(message.structured_content["subject"], message.structured_content["codes"])
            finally:
                deleted = await client.call_tool("delete_inbox", {"inbox_id": inbox["id"]})
                if deleted.is_error:
                    raise RuntimeError(deleted.content)

asyncio.run(main())

المرفقات

تعيد قراءة الرسالة فهرس كل مرفق واسم ملفه وحجمه. نزّل أي مرفق عبر GET …/attachments/{index}: تُقدَّم الملفات التي لا يتجاوز حجمها 10 ميغابايت بنوع application/octet-stream وبأسماء ملفات منقّحة. يرى عملاء MCP القائمة نفسها ويُنزّلون عبر نقطة نهاية REST هذه.

متى تستخدم هذه الخدمة بدلًا من أدوات أخرى

يلتقط Mailpit وMailHog وEthereal البريد الذي يرسله تطبيقك إلى خادم SMTP محلي أو وهمي، وهذا مثالي عندما تتحكم في إعدادات SMTP. أما هذه الصناديق فعناوين حقيقية على نطاق عام، لذا يمكن لأي مرسل الوصول إليها: خدمة خارجية، أو خادم staging يستخدم مزوّد البريد الحقيقي لديك، أو مسار قريب من بيئة الإنتاج.

واجهات API العامة للبريد المؤقت، مثل mail.tm أو Guerrilla Mail، مصممة للعناوين المؤقتة الشخصية. أما هذه الواجهة فمصممة للأتمتة: مفاتيح محددة الصلاحيات والمدة، وصندوق لكل اختبار، وانتظار محدود عبر long polling، واكتشاف الرموز والروابط، وخادم MCP.

غير مشمول: إرسال البريد، والرسائل النصية SMS، ومعاينات HTML أو البريد العشوائي، والنطاقات المخصصة، وتسجيل الدخول عبر OAuth لعملاء MCP.

الاحتفاظ والحدود والأمان

يمكن لنطاق الاستقبال أن يحدد مدة بقاء أقصر أو حدًا أقل لعدد الرسائل.

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

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