Temporary Email Service API Documentation

This API provides a temporary email address and allows retrieval of emails sent to that address. It's built as a Vercel Function.

Base URL:

/api/tempmail (This is a relative URL. Replace with your actual Vercel deployment URL if serving the HTML from a different domain)

Endpoints:

1. GET /api/tempmail

Generates a new temporary email address.

Request Body:

None

Response:

Returns a JSON object containing the email address, ID, and token.

Status Codes:

• 200 OK: Success.
• 500 Internal Server Error: Failed to generate the email address. Check the server logs for details.

Response Body (Success - 200 OK):

{
    "address": "random_string@example.com",  // The temporary email address.
    "id": "unique_identifier",             // A unique identifier for the email address.
    "token": "authentication_token"         // A token used for authentication when retrieving emails.
}
    

Response Body (Error - 500 Internal Server Error):

{
    "error": "Failed to generate email. See server logs."  // Description of the error.
}
    

Example Request:

curl /api/tempmail
    

Example Response (Success):

{
    "address": "abcdef123456@example.com",
    "id": "g8hijklmno",
    "token": "pqrstuvwxyz123"
}
    

2. POST /api/tempmail

Retrieves emails sent to a specific temporary email address.

Request Body:

A JSON object containing the id and token obtained when generating the email address.

{
    "id": "unique_identifier",
    "token": "authentication_token"
}
    

Response:

Returns a JSON array containing the email messages.

Status Codes:

• 200 OK: Success.
• 400 Bad Request: Missing id or token in the request body.
• 500 Internal Server Error: Failed to fetch emails. Check the server logs for details.

Response Body (Success - 200 OK):

[
    {
        "id": "7e51abe6-738b-47ca-b912-c1dbab6e9be6",
        "received_at": 1739071735,
        "sender": "someone@outlook.com",
        "from_name": "Sender Name",
        "from_address": "someone@outlook.com",
        "subject": "test",
        "body_html": "...",
        "body_plain": "test111*11*",
        "ttl": 1739158102
    },
    // ... more emails
]
    

Response Body (Success - 200 OK - No Emails):

[]  // Empty array indicates no emails have been received yet.
    

Response Body (Error - 400 Bad Request):

{
    "error": "Missing id or token in request body."
}
    

Response Body (Error - 500 Internal Server Error):

{
    "error": "Failed to fetch emails. See server logs."
}
    

Example Request:

curl -X POST \
  /api/tempmail \
  -H 'Content-Type: application/json' \
  -d '{
    "id": "g8hijklmno",
    "token": "pqrstuvwxyz123"
  }'
    

Example Response (Success with Emails):

[
    {
        "id": "7e51abe6-738b-47ca-b912-c1dbab6e9be6",
        "received_at": 1739071735,
        "sender": "iscyclebai@outlook.com",
        "from_name": "Cycle Bai",
        "from_address": "iscyclebai@outlook.com",
        "subject": "test",
        "body_html": "...",
        "body_plain": "test111*11*",
        "ttl": 1739158102
    }
]
    

Authentication:

The API uses a token-based authentication scheme. The token is returned when generating a new email address and must be included in the request body when retrieving emails.

Error Handling:

The API returns appropriate HTTP status codes to indicate success or failure. Error responses include a JSON object with an error field providing a description of the error. Detailed error messages are logged on the server (Vercel's logs).

Rate Limiting:

Important: The underlying tempmailonline.co service likely has rate limits. You should implement retry logic with exponential backoff in your client-side code to handle rate limiting errors. Consider adding your own rate limiting mechanism to the Vercel Function to prevent abuse and protect the upstream service.

Important Notes:

• The underlying implementation relies on scraping a JavaScript file from tempmailonline.co. This URL is subject to change when the target website updates. You will need to monitor the website and update the JavaScript file URL in your code accordingly to prevent breakage.
• The stability of this API depends on the reliability of the tempmailonline.co service.
• Be aware that temporary email services can be used for malicious purposes. Implement security measures to prevent abuse of your API.
• If you are accessing this API from a different domain, you may need to configure CORS (Cross-Origin Resource Sharing) in your Vercel Function to allow requests from your client-side application.