Services & APIs
Temp Mail API
Disposable temporary email inbox API for CI/CD automation, QA testing, and spam prevention.
Disposable Temp Mail API
The 1st Services Temp Mail API allows developers to generate ephemeral email inboxes on-the-fly, listen for incoming emails via webhooks or polling, and extract OTP verification codes, magic links, and attachments programmatically.
Use Cases
- CI/CD & E2E Testing: Automate sign-up flows, email verification links, and password resets in Playwright/Cypress.
- Privacy & Spam Shielding: Prevent your personal or corporate domain from being flooded with marketing mail.
- Webhook Ingestion: Convert incoming emails into structured JSON webhooks for internal automation.
1. Generate an Ephemeral Inbox
Endpoint
POST https://api.1st-services.com/v1/tempmail/inboxes
Request Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
prefix | string | No | Custom local-part prefix (e.g. test-signup-123). |
domain | string | No | Available temp domain or your verified custom domain. |
ttl_minutes | integer | No | Lifetime of mailbox (1 to 1440 minutes, default: 60). |
webhook_url | string | No | Webhook URL to dispatch newly received emails to. |
cURL Example
cURL
curl -X POST https://api.1st-services.com/v1/tempmail/inboxes \
-H "Authorization: Bearer $FIRST_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"prefix": "qa-user-991",
"ttl_minutes": 120,
"webhook_url": "https://myapp.com/api/webhooks/mail"
}'
Response
{
"status": "success",
"data": {
"inbox_id": "inbox_9281740",
"email_address": "qa-user-991@1stmail.org",
"ttl_minutes": 120,
"expires_at": "2026-08-24T16:10:00Z",
"message_count": 0,
"created_at": "2026-08-24T14:10:00Z"
}
}
2. List Received Emails
Fetch messages received by an inbox:
GET https://api.1st-services.com/v1/tempmail/inboxes/:inbox_id/messages
Response Example
{
"status": "success",
"data": [
{
"id": "msg_0019284",
"sender": "no-reply@authservice.com",
"subject": "Your verification code: 849201",
"snippet": "Hello! Your 6-digit one-time passcode is 849201...",
"otp_code": "849201",
"received_at": "2026-08-24T14:11:30Z",
"has_attachments": false
}
]
}
3. Get Full Email Details
Retrieve parsed HTML, plain text, and attachment metadata for a specific message:
GET https://api.1st-services.com/v1/tempmail/messages/:message_id
Response Example
{
"status": "success",
"data": {
"id": "msg_0019284",
"sender": "no-reply@authservice.com",
"recipient": "qa-user-991@1stmail.org",
"subject": "Your verification code: 849201",
"html_body": "<div><h2>Welcome!</h2><p>Your OTP is <strong>849201</strong></p></div>",
"text_body": "Welcome! Your OTP is 849201",
"parsed_links": [
"https://authservice.com/verify?token=xyz998811"
],
"otp_code": "849201",
"headers": {
"Message-ID": "<abc@authservice.com>",
"SPF": "pass",
"DKIM": "pass"
}
}
}
4. Automated E2E Test Example (Playwright)
tests/auth.spec.ts
import { test, expect } from '@playwright/test'
import { FirstClient } from '@1st-services/sdk'
const first = new FirstClient({ apiKey: process.env.FIRST_API_KEY })
test('User signup with email OTP verification', async ({ page }) => {
// 1. Create temporary test mailbox
const inbox = await first.tempMail.createInbox({ ttlMinutes: 15 })
// 2. Submit signup form with generated temp email
await page.goto('https://myapp.com/signup')
await page.fill('#email', inbox.address)
await page.click('button[type="submit"]')
// 3. Wait for email and extract OTP code
const message = await first.tempMail.waitForMessage(inbox.id, { timeoutMs: 15000 })
expect(message.otpCode).toBeDefined()
// 4. Input OTP code and verify success
await page.fill('#otp', message.otpCode!)
await page.click('#verify-btn')
await expect(page).toHaveURL(/.*dashboard/)
})