API Documentation

curl -X POST https://otpbox.app/api/inbox   -H "Authorization: Bearer YOUR_API_KEY"

# or
curl -X POST https://otpbox.app/api/inbox   -H "x-api-key: YOUR_API_KEY"

{
  "id": "abc123xyz789",
  "email": "abc123xyz789@box.otpbox.app",
  "expiresAt": 1704153600000,
  "token": "def456uvw012..."
}

curl -X POST https://otpbox.app/api/inbox

{
  "inbox": {
    "id": "abc123xyz789",
    "email": "abc123xyz789@box.otpbox.app",
    "token": "def456uvw012...",
    "createdAt": 1704150000000,
    "expiresAt": 1704153600000
  },
  "messages": [
    {
      "id": "msg001",
      "inboxId": "abc123xyz789",
      "from": "noreply@service.com",
      "subject": "Your verification code",
      "body": "Your code is: 123456",
      "otp": "123456",
      "magicLink": null,
      "receivedAt": 1704150100000
    }
  ]
}

{
  "otp": "123456",
  "link": "https://service.com/verify?token=...",
  "from": "noreply@service.com",
  "subject": "Your verification code",
  "receivedAt": 1704150100000
}

{
  "error": "No messages found"
}

This endpoint returns 404 when the inbox exists but has no messages yet. Use a wait/retry loop in your automation (see CI examples below).

Using Pro in CI

Pro: 24-Hour Message History

# Fetch all messages from the last 24h
curl https://otpbox.app/api/pro/history \
  -H "Authorization: Bearer YOUR_PRO_KEY"

# Filter by timestamp (Unix ms)
curl "https://otpbox.app/api/pro/history?since=1704150000000" \
  -H "Authorization: Bearer YOUR_PRO_KEY"

# Response includes all messages across all your inboxes
{
  "messages": [
    {
      "id": "abc123",
      "from": "noreply@app.com",
      "subject": "Verify your email",
      "otp": "123456",
      "magicLink": "https://app.com/verify?token=...",
      "receivedAt": 1704151234567,
      "inboxId": "xyz789"
    }
  ],
  "count": 1,
  "retention": "24 hours"
}

Shell Script Example

#!/bin/bash
set -e

# 1. Create disposable inbox (optional Pro: export OTPBOX_API_KEY)
echo "Creating inbox..."
AUTH_HEADER=()
if [ -n "$OTPBOX_API_KEY" ]; then
  AUTH_HEADER=(-H "Authorization: Bearer $OTPBOX_API_KEY")
fi
RESPONSE=$(curl -s -X POST https://otpbox.app/api/inbox "${AUTH_HEADER[@]}")
TOKEN=$(echo "$RESPONSE" | jq -r '.token')
EMAIL=$(echo "$RESPONSE" | jq -r '.email')

echo "Inbox: $EMAIL"
echo "Token: $TOKEN"

# 2. Trigger your app to send verification email to $EMAIL
# Example: curl -X POST https://yourapp.com/signup -d "email=$EMAIL"
echo "Triggering verification email..."
# ... your app logic here ...

# 3. Poll for OTP (unrestricted - poll as needed)
echo "Waiting for OTP..."
MAX_ATTEMPTS=10
SLEEP_SECONDS=3

for i in $(seq 1 $MAX_ATTEMPTS); do
  RESPONSE=$(curl -s https://otpbox.app/api/inbox/$TOKEN/latest)
  OTP=$(echo "$RESPONSE" | jq -r '.otp // empty')
  
  if [ -n "$OTP" ] && [ "$OTP" != "null" ]; then
    echo "✓ Got OTP: $OTP"
    
    # 4. Use the OTP in your test
    # Example: curl -X POST https://yourapp.com/verify -d "code=$OTP"
    exit 0
  fi
  
  echo "  Attempt $i/$MAX_ATTEMPTS - no message yet, waiting..."
  sleep $SLEEP_SECONDS
done

echo "✗ Timeout: No OTP received after $MAX_ATTEMPTS attempts"
exit 1

GitHub Actions Example

name: E2E Verification Test

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Create OTPBox inbox
        id: inbox
        # Free still works without the secret. Optional: set OTPBOX_API_KEY for Pro
        # (matrix runners that hit Free 429 / need 120/hr + 6h TTL).
        env:
          OTPBOX_API_KEY: ${{ secrets.OTPBOX_API_KEY }}
        run: |
          AUTH=()
          if [ -n "$OTPBOX_API_KEY" ]; then
            AUTH=(-H "Authorization: Bearer $OTPBOX_API_KEY")
          fi
          RESPONSE=$(curl -s -X POST https://otpbox.app/api/inbox "${AUTH[@]}")
          echo "token=$(echo $RESPONSE | jq -r '.token')" >> $GITHUB_OUTPUT
          echo "email=$(echo $RESPONSE | jq -r '.email')" >> $GITHUB_OUTPUT
      
      - name: Trigger signup with OTPBox email
        run: |
          curl -X POST https://yourapp.com/api/signup \
            -H "Content-Type: application/json" \
            -d '{"email": "${{ steps.inbox.outputs.email }}"}'
      
      - name: Wait for OTP
        id: otp
        run: |
          for i in {1..10}; do
            RESPONSE=$(curl -s https://otpbox.app/api/inbox/${{ steps.inbox.outputs.token }}/latest)
            OTP=$(echo "$RESPONSE" | jq -r '.otp // empty')
            
            if [ -n "$OTP" ] && [ "$OTP" != "null" ]; then
              echo "otp=$OTP" >> $GITHUB_OUTPUT
              echo "✓ Received OTP: $OTP"
              exit 0
            fi
            
            echo "Waiting for OTP (attempt $i/10)..."
            sleep 3
          done
          
          echo "✗ Timeout waiting for OTP"
          exit 1
      
      - name: Verify OTP
        run: |
          curl -X POST https://yourapp.com/api/verify \
            -H "Content-Type: application/json" \
            -d '{"code": "${{ steps.otp.outputs.otp }}"}'

Rate Limits & Best Practices

Wait/Retry Pattern

Email delivery typically takes 1-5 seconds. The /latest endpoint returns 404 with { "error": "No messages found" } when the inbox exists but has no messages yet.

Recommended pattern: Poll every 3 seconds for up to 30 seconds (10 attempts). Since polling is unrestricted, feel free to poll more aggressively if needed.

# Minimal wait/retry in curl (polling is unrestricted)
for i in {1..10}; do
  OTP=$(curl -s https://otpbox.app/api/inbox/$TOKEN/latest | jq -r '.otp // empty')
  [ -n "$OTP" ] && [ "$OTP" != "null" ] && break
  sleep 3
done