TempMailGrab API Tutorial

Prerequisites

• A TempMailGrab account — create one at the dashboard
• An API key (generated in the dashboard after signing in)
• curl, Node.js, or Python — examples are provided for all three

Step 1: Get your API key

Sign in to the TempMailGrab dashboard. Under "API Keys", click "Create key" and give it a label (e.g. "testing-pipeline"). The key is shown once — copy it immediately and store it in your environment or secret manager.

export TMG_API_KEY="tmg_sk_..."

Step 2: Create a private inbox

curl -X POST https://tempmailgrab.com/api/v1/inbox   -H "Authorization: Bearer $TMG_API_KEY"   -H "Content-Type: application/json"   -d '{"prefix": "ci-test", "ttl_seconds": 3600}'

Response:

{
  "id": "inb_01abc123...",
  "address": "ci-test-a1b2c3@tempmailgrab.com",
  "created_at": 1709000000,
  "expires_at": 1709003600
}

Step 3: Poll for messages

curl https://tempmailgrab.com/api/v1/inbox/$INBOX_ID/messages   -H "Authorization: Bearer $TMG_API_KEY"

Messages include pre-extracted OTP codes and verification links — no regex required:

{
  "messages": [{
    "id": "msg_...",
    "sender": "no-reply@github.com",
    "subject": "[GitHub] Verify your email address",
    "extracted_otp": "847293",
    "extracted_links": ["https://github.com/users/confirm_email?token=..."],
    "created_at": 1709000045
  }]
}

Step 4: Use in a test (Node.js example)

const API = 'https://tempmailgrab.com/api/v1';
const headers = { Authorization: 'Bearer ' + process.env.TMG_API_KEY };

async function createInbox() {
  const res = await fetch(API + '/inbox', { method: 'POST', headers });
  return res.json();
}

async function waitForOtp(inboxId, timeoutMs = 30000) {
  const deadline = Date.now() + timeoutMs;
  while (Date.now() < deadline) {
    const res = await fetch(API + '/inbox/' + inboxId + '/messages', { headers });
    const { messages } = await res.json();
    const msg = messages.find(m => m.extracted_otp);
    if (msg) return msg.extracted_otp;
    await new Promise(r => setTimeout(r, 2000));
  }
  throw new Error('OTP timeout');
}

const { id, address } = await createInbox();
await signUpWithEmail(address);
const otp = await waitForOtp(id);
await submitOtp(otp);

Step 5: Inject a test message (development only)

curl -X POST https://tempmailgrab.com/api/v1/inbox/$INBOX_ID/test-message   -H "Authorization: Bearer $TMG_API_KEY"   -H "Content-Type: application/json"   -d '{"subject": "Your code is 123456", "text": "Use this code: 123456"}'

Step 6: Real-time delivery with webhooks

curl -X POST https://tempmailgrab.com/api/v1/inbox/$INBOX_ID/webhook   -H "Authorization: Bearer $TMG_API_KEY"   -H "Content-Type: application/json"   -d '{"url": "https://your-server.com/hooks/tmg"}'

Each delivery is signed with X-TMG-Signature (HMAC-SHA256). Verify it before processing to ensure authenticity.

Rate limits

The API allows 100 requests per second per API key. If you exceed the limit you receive a 429 — implement exponential backoff. For the complete endpoint reference, see the API documentation.