← Back to Guides

API Integration Guide

By TempMailSpot Editorial Team••2 min read

Owned-inbox API quickstart

Contract version: v1. Source reviewed 30 September 2026. Run this only with test inboxes you create and synthetic data. Production provider availability is not established by local contract tests.

Create an inbox with POST /api/v1/generate. Save the returned email and token; the token is a bearer credential, never put it in shared logs or source control. Read messages with GET /api/v1/inbox?email=... and an Authorization: Bearer header.

const base = 'https://tempmailspot.com';
const created = await fetch(base + '/api/v1/generate', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({})
});
if (!created.ok) throw new Error('Generation failed: ' + created.status);
const { email, token } = await created.json();
const inbox = await fetch(base + '/api/v1/inbox?email=' + encodeURIComponent(email), {
  headers: { Authorization: 'Bearer ' + token }
});
if (!inbox.ok) throw new Error('Inbox request failed: ' + inbox.status);
const { messageCount, messages } = await inbox.json();
console.log({ messageCount, messages });

Response and failure contract

Creation returns HTTP 201 with email, token, createdAt, expiresAt and inboxUrl. expiresAt is an advisory browser timer, not an enforced provider deletion deadline; inboxUrl opens the homepage and does not transfer the credential. Inbox retrieval returns email, messageCount and messages with id, from, subject, receivedAt, preview and hasAttachments.

  • 400: invalid input or missing session token. Inbox errors use an error string and code.
  • 403 during generation: geographic restriction or security challenge; the mailbox response uses success: false and a code such as CAPTCHA_REQUIRED or GEO_BLOCKED. Complete any required verification rather than bypassing it.
  • 429: rate limit. Read Retry-After and back off. The free API window is 100 requests per hour; generation also passes the mailbox endpoint limits.
  • 503 during generation: provider unavailable, with success: false, an error string and Retry-After.
  • 410 during inbox retrieval: provider reported expiry, with code EMAIL_EXPIRED.
  • 502 during inbox retrieval: provider retrieval failed, with code INBOX_ERROR.
  • 500: unexpected server failure, with code INTERNAL_SERVER_ERROR.

Test fixture teardown

Temporary mail does not remove rows from your application. Scope cleanup to the fixture created by the current test and execute it even after assertion failures.

let fixtureId;
try {
  fixtureId = await createOwnedTestUser(email);
  await verifySignupEmail(email, token);
} finally {
  if (fixtureId) await deleteOwnedTestUser(fixtureId);
}

The fixture helpers above belong to your application. Use sanitized HTML previews for content checks; test Gmail, Outlook, mobile rendering and inbox placement separately. Poll with backoff and stop on expiry.

API support ? Create an owned demo inbox ? Testing guidance