Wait API

The Wait API allows you to wait for a new email to arrive in a specified mailbox using Long Polling. This eliminates the need for rapid polling, reduces your request overhead, and ensures you get emails as soon as they arrive.

Important Considerations

Plan Requirement: Available on Developer plan or above.
Billing: High-value endpoint; 1 successful wait call consumes 10 monthly requests.
Connections: Only 1 concurrent wait request per inbox is allowed.

GET /v1/inboxes/{inbox}/wait

Hold the connection open until a new message arrives or the timeout is reached.

Query Parameters

Parameter	Type	Description
`timeout`	integer	Maximum seconds to wait before returning a timeout response. Default: 30, Min: 10, Max: 60.
`since`	string	Optional. Provide the ID of the last message seen. If a newer message already exists, it returns immediately instead of waiting.

curl

curl "https://api2.freecustom.email/v1/inboxes/mytest@ditapi.info/wait?timeout=45" \
  -H "Authorization: Bearer fce_your_api_key"

Responses

200New message received

json

{
  "success": true,
  "message": "New message received",
  "data": {
    "id": "msg_01jqz3k4m5n6p7q8r9s0t1u2v3",
    "from": "noreply@github.com",
    "subject": "Your GitHub verification code",
    "date": "2026-03-04T09:55:00.000Z",
    "has_attachment": false,
    "otp": "482931",
    "verification_link": "https://github.com/verify?token=abc123"
  }
}

If no message arrives within the specified timeout period, the API will gracefully return a timeout response. You can immediately initiate another wait request.

200Timeout Reached

json

{
  "success": false,
  "message": "Timeout reached"
}

403Plan or Plan Limit Restrictions

json

{
  "success": false,
  "error": "forbidden",
  "message": "Wait API is not available on your current plan."
}

429Too Many Concurrent Waits

json

{
  "success": false,
  "error": "rate_limit",
  "message": "A wait operation is already in progress for this inbox."
}

Code Examples

Node.js (Fetch)

javascript

async function waitForEmail(inbox, apiKey) {
  try {
    const url = `https://api2.freecustom.email/v1/inboxes/${inbox}/wait?timeout=60`;
    const response = await fetch(url, {
      headers: { 'Authorization': `Bearer ${apiKey}` }
    });
    
    const data = await response.json();
    if (data.success) {
      console.log('New email arrived:', data.data.subject);
      return data.data;
    } else {
      console.log('Timeout reached. Retrying...');
      return waitForEmail(inbox, apiKey); // Optional recursive retry
    }
  } catch (error) {
    console.error('Wait failed:', error);
  }
}

Python (Requests)

python

import requests

def wait_for_email(inbox, api_key):
    url = f"https://api2.freecustom.email/v1/inboxes/{inbox}/wait"
    headers = {"Authorization": f"Bearer {api_key}"}
    params = {"timeout": 60}
    
    try:
        # Note: requests timeout should be slightly longer than API timeout
        response = requests.get(url, headers=headers, params=params, timeout=65)
        data = response.json()
        
        if data.get("success"):
            print("New email arrived:", data["data"]["subject"])
            return data["data"]
        else:
            print("Timeout reached.")
            return None
    except requests.exceptions.RequestException as e:
        print("Wait failed:", e)
        return None