Developer API

API Documentation

Generate temporary emails programmatically with our REST API. Free tier with 100 requests/hour.

Quick Start

Our API is RESTful and returns JSON responses. No authentication required for the free tier.

Base URL

https://tempmailspot.com/api/v1

Generate Email

POST /api/v1/generate

Create a new temporary email address with optional expiration time.

Request Body

{
  "domain": "string (optional)",
  "expiresIn": number (optional, 60-3600 seconds)
}

Response

{
  "email": "random123@domain.com",
  "expiresAt": 1234567890000,
  "inboxUrl": "https://tempmailspot.com?email=...",
  "createdAt": 1234567890000
}

Example

// Generate temporary email
const response = await fetch('https://tempmailspot.com/api/v1/generate', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    expiresIn: 600 // Optional: 600 seconds (10 minutes)
  })
});

const data = await response.json();
console.log(data.email); // Generated email address
console.log(data.expiresAt); // Expiration timestamp

Check Inbox

GET /api/v1/inbox

Retrieve all messages for a temporary email address with pagination support.

Query Parameters

email (required): Temporary email address
limit (optional): Number of messages to return (1-100, default: 10)
offset (optional): Number of messages to skip (default: 0)

Response

{
  "email": "example@domain.com",
  "messageCount": 5,
  "messages": [
    {
      "id": "msg_123",
      "from": "sender@example.com",
      "subject": "Welcome!",
      "receivedAt": 1234567890000,
      "preview": "Hello and welcome...",
      "hasAttachments": false
    }
  ]
}

Example

// Check inbox for messages
const email = 'example@tempmail.com';
const response = await fetch(`https://tempmailspot.com/api/v1/inbox?email=${email}&limit=10`);

const data = await response.json();
console.log(data.messageCount); // Total messages
console.log(data.messages); // Array of messages

Read Message

GET /api/v1/message/:id

Retrieve full message content including HTML body and attachments.

Query Parameters

email (required): Temporary email address

Response

{
  "id": "msg_123",
  "from": "sender@example.com",
  "to": "example@domain.com",
  "subject": "Welcome!",
  "receivedAt": 1234567890000,
  "htmlBody": "<html>...</html>",
  "textBody": "Plain text content",
  "headers": {},
  "attachments": []
}

Example

// Read full message
const messageId = 'msg_123';
const email = 'example@tempmail.com';
const response = await fetch(`https://tempmailspot.com/api/v1/message/${messageId}?email=${email}`);

const data = await response.json();
console.log(data.subject);
console.log(data.htmlBody);

Rate Limits

Free Tier

100 requests per hour

No authentication required

Registered

1,000 requests per hour

API key required (coming soon)

Response Headers

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1234567890

Error Handling

All errors return JSON with an error code and message.

INVALID_REQUEST400

Invalid request parameters

EMAIL_NOT_FOUND404

Email address not found

MESSAGE_NOT_FOUND404

Message not found

RATE_LIMIT_EXCEEDED429

Rate limit exceeded

INTERNAL_SERVER_ERROR500

Server error