Edgemail

Inbox API

Use this API when an agent needs to inspect a temporary inbox on smtp.idont.date over HTTP.

Assume smtp.idont.date is an external service that already exposes this API.

Any address at @idont.date works without registration or setup. Agents should pick inbox names that are human-readable and specific to the task, with optional short numbering when needed.

Examples:

• that_subscription_77@idont.date
• github_reset_2@idont.date
• travel_booking@idont.date

Prefer names that make it obvious what the inbox is for. This makes later polling and message review easier.

Delivery is not instant. New mail may take at least 10 seconds to appear, and sometimes longer. Agents should assume some delay and use polling with a finite timeout instead of expecting immediate delivery.

Endpoints

List messages in an inbox

Request:

GET http://smtp.idont.date/inbox?inbox=<email@domain>&page=1

Response:

{
  "mail": [
    {
      "id": 123,
      "date": "2026-05-17 10:00:00.000",
      "recipients": ["that_subscription_77@idont.date"],
      "sender": "<sender@example.com>",
      "subject": "Welcome"
    }
  ],
  "has_more_pages": false
}

Use this when you need the current mailbox contents or when you want to find the newest message ID before fetching a full message. Each page contains at most 10 messages. If page is omitted, the API returns page 1.

Read a single message

Request:

GET http://smtp.idont.date/inbox/<id>

Response:

{
  "id": 123,
  "date": "2026-05-17 10:00:00.000",
  "recipients": ["that_subscription_77@idont.date"],
  "sender": "<sender@example.com>",
  "subject": "Welcome",
  "body": "Hello from edgemail"
}

Use this after the list endpoint tells you which message you want.

Recommended agent workflow

Read the inbox

1. Choose a readable inbox name such as that_subscription_77@idont.date.
2. Call GET http://smtp.idont.date/inbox?inbox=<email@domain>&page=1.
3. Inspect the returned mail list by date or id.
4. Call GET http://smtp.idont.date/inbox/<id> for the message you need in full.
5. If has_more_pages is true, request page=2, then page=3, and so on until you find what you need or pages are exhausted.

Wait for a message by polling

Use polling when you expect a message to arrive soon.

1. Choose a readable inbox name such as that_subscription_77@idont.date.
2. Call GET http://smtp.idont.date/inbox?inbox=<email@domain>&page=1 once and record the newest known id.
3. Sleep for 5 to 10 seconds.
4. Call GET http://smtp.idont.date/inbox?inbox=<email@domain>&page=1 again.
5. If a newer id appears, fetch it with GET http://smtp.idont.date/inbox/<id>.
6. If nothing new appears, keep polling every 5 to 10 seconds until your own task timeout is reached.

Practical guidance:

• Expect delivery to take at least 10 seconds in normal cases, and sometimes longer.
• Prefer a 5 second interval when waiting on an interactive flow like sign-in or verification.
• Prefer a 10 second interval when latency is less important.
• Keep your own overall timeout finite, for example 2 to 5 minutes.
• Compare by id or by the first item in the returned mail list, since the API returns messages newest first.

Error handling

• 400 means the request was malformed, for example missing the inbox query parameter.
• 404 means the message ID was not found.
• 503 means the API has already served more than 100 requests and will reject further ones.
• 504 means the server-side request timed out after 30 seconds.

If you receive 503, stop polling and switch to a fresh session or different inbox. If you receive 504, retry the same request after a short delay.

Source: psarna/edgemail — distributed by TomeVault.