[ PTFR MAIL API ]

API DOCUMENTATION // APIドキュメント

API BASE: https://mail-api.potefura.jp
Version: 1.0.0

Overview

Ptfr Mail API は、使い捨てメールアドレスの生成・管理・メッセージ取得を提供するRESTful APIです。

すべてのエンドポイントはJSON形式でレスポンスを返します。

📡 Base URL: https://mail-api.potefura.jp
🔒 HTTPS: 必須
🔓 認証: 不要
📦 Content-Type: application/json

Endpoints

GET /domains

利用可能なドメインのリストを取得します。

Response

{
  "domains": [
    "example.com",
    "mail.example.com"
  ]
}
POST /create

新しい使い捨てメールアドレスを生成します。

Query Parameters

Parameter Type Required Description
domain string Optional 使用するドメイン。省略時は最初のドメインを使用
tag string Optional アドレスに追加するタグ（例: username+tag@domain.com）

Response

{
  "address": "a1b2c3d4@example.com"
}

Example Request

POST https://mail-api.potefura.jp/create?domain=mail.example.com&tag=signup

Response:
{
  "address": "x7y8z9@mail.example.com"
}
GET /messages

指定したアドレスの受信メッセージ一覧を取得します。

Query Parameters

Parameter Type Required Description
address string Required メールアドレス

Response

{
  "address": "a1b2c3d4@example.com",
  "messages": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "to": "a1b2c3d4@example.com",
      "from": "noreply@service.com",
      "subject": "Welcome to Service!",
      "receivedAt": "2024-01-15T12:34:56.789Z",
      "preview": "Thank you for signing up...",
      "cleanPreview": "Thank you for signing up...",
      "raw": "From: noreply@service.com\n...",
      "text": "Plain text content",
      "cleanText": "Plain text content"
    }
  ]
}

Example Request

GET https://mail-api.potefura.jp/messages?address=a1b2c3d4@example.com
GET /messages/:id

特定のメッセージの詳細を取得します。

Path Parameters

Parameter Type Required Description
id string Required メッセージID（UUID）

Response

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "to": "a1b2c3d4@example.com",
  "from": "noreply@service.com",
  "subject": "Welcome to Service!",
  "receivedAt": "2024-01-15T12:34:56.789Z",
  "preview": "Thank you for signing up...",
  "cleanPreview": "Thank you for signing up...",
  "raw": "From: noreply@service.com\n...",
  "text": "Plain text content",
  "cleanText": "Plain text content"
}
GET /messages/otp

指定したアドレスの最新のOTP（ワンタイムパスワード）を抽出します。

Query Parameters

Parameter Type Required Description
address string Required メールアドレス

Response

{
  "address": "a1b2c3d4@example.com",
  "latest": {
    "messageId": "550e8400-e29b-41d4-a716-446655440000",
    "subject": "Your verification code",
    "receivedAt": "2024-01-15T12:34:56.789Z",
    "code": "123456"
  },
  "all": [
    {
      "messageId": "550e8400-e29b-41d4-a716-446655440000",
      "subject": "Your verification code",
      "receivedAt": "2024-01-15T12:34:56.789Z",
      "code": "123456"
    }
  ]
}
ℹ️ OTP抽出ロジック: 4〜8桁の純粋な数字列を検出します。英数字混在コードは除外されます。
GET /messages/verify-link

指定したアドレスの認証・確認リンクを抽出します。

Query Parameters

Parameter Type Required Description
address string Required メールアドレス

Response

{
  "address": "a1b2c3d4@example.com",
  "results": [
    {
      "messageId": "550e8400-e29b-41d4-a716-446655440000",
      "subject": "Verify your email",
      "links": [
        "https://service.com/verify?token=abc123xyz789"
      ]
    }
  ]
}
ℹ️ リンク抽出ロジック:
  • verify、confirm、activate、validate等のキーワードを含むURLを優先
  • リダイレクトを追跡して最終的なURLを取得
  • 名前空間URL（w3.org等）を除外

Usage Examples

JavaScript / Fetch API

// アドレスを作成
const createResponse = await fetch('https://mail-api.potefura.jp/create', {
  method: 'POST'
});
const { address } = await createResponse.json();
console.log('Address:', address);

// メッセージを取得
const messagesResponse = await fetch(
  `https://mail-api.potefura.jp/messages?address=${encodeURIComponent(address)}`
);
const { messages } = await messagesResponse.json();
console.log('Messages:', messages);

// OTPを取得
const otpResponse = await fetch(
  `https://mail-api.potefura.jp/messages/otp?address=${encodeURIComponent(address)}`
);
const { latest } = await otpResponse.json();
console.log('Latest OTP:', latest?.code);

cURL

# アドレスを作成
curl -X POST https://mail-api.potefura.jp/create

# メッセージを取得
curl "https://mail-api.potefura.jp/messages?address=a1b2c3d4@example.com"

# OTPを取得
curl "https://mail-api.potefura.jp/messages/otp?address=a1b2c3d4@example.com"

# 認証リンクを取得
curl "https://mail-api.potefura.jp/messages/verify-link?address=a1b2c3d4@example.com"

Python

import requests

# アドレスを作成
response = requests.post('https://mail-api.potefura.jp/create')
address = response.json()['address']
print(f'Address: {address}')

# メッセージを取得
response = requests.get(
    'https://mail-api.potefura.jp/messages',
    params={'address': address}
)
messages = response.json()['messages']
print(f'Messages: {len(messages)}')

Data Retention

⏰ データ保持期間:
  • すべてのメッセージは 30日後に自動削除 されます
  • アドレスインデックスも同様に30日で期限切れになります
  • 月次クリーンアップジョブが期限切れのメールボックスを削除します

このポリシーにより、プライバシーが保護され、ストレージコストが最適化されます。

Error Codes

Status Code Description
200 成功
201 作成成功（アドレス生成時）
400 不正なリクエスト（パラメータ不足など）
404 リソースが見つかりません
500 サーバーエラー

Error Response Format

{
  "error": "Error message description"
}

Rate Limits

Cloudflare Workers の制限内で動作します：

レート制限に達した場合でも、APIはエラーを返さずに古いメッセージを自動的に削除します。