Developer API

MailGX REST API — disposable email for QA & CI/CD

Create temp mail inboxes programmatically, poll OTP verification emails, and automate signup testing — with curl, Node.js, Python, Postman, and GitHub Actions examples. Read the OTP testing guide or compare API plan limits on pricing.

Developer resources

High-intent, shareable docs for engineering teams — import, fork, and integrate in minutes.

Quick start — create inbox & capture OTP

Generate a disposable address, trigger your signup flow, then poll messages until the verification code appears. Examples below use your MailGX API key from the dashboard.

1. Create a mailbox

curl
curl -X POST https://mailgx.com/api/v1/mailboxes \
  -H "Authorization: Bearer rm_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "autoGenerate": true,
    "domain": "mailgx.com"
  }'

2. Poll for OTP / verification email

curl
# Poll until verification email arrives
curl -H "Authorization: Bearer rm_live_your_key" \
  "https://mailgx.com/api/v1/messages?mailbox=qa-signup@mailgx.com&limit=5"
Tip: Store MAILGX_API_KEY in CI secrets. Never commit API keys to git. Use a fresh mailbox per test run to avoid cross-test contamination.

Email testing in CI/CD

Run signup and OTP verification tests on every pull request without SMTP infrastructure or personal inboxes. This GitHub Actions workflow creates a MailGX mailbox, triggers your staging signup endpoint, polls for the OTP email, and fails the build if verification mail never arrives.

GitHub Actions — OTP signup test
# .github/workflows/email-signup-test.yml
name: Email signup QA

on: [push, pull_request]

jobs:
  otp-flow:
    runs-on: ubuntu-latest
    env:
      MAILGX_API_KEY: ${{ secrets.MAILGX_API_KEY }}
      MAILGX_BASE_URL: https://mailgx.com
      APP_SIGNUP_URL: ${{ secrets.STAGING_SIGNUP_URL }}

    steps:
      - uses: actions/checkout@v4

      - name: Create disposable inbox
        id: inbox
        run: |
          RESP=$(curl -sS -X POST "$MAILGX_BASE_URL/api/v1/mailboxes" \
            -H "Authorization: Bearer $MAILGX_API_KEY" \
            -H "Content-Type: application/json" \
            -d '{"autoGenerate":true,"domain":"mailgx.com"}')
          echo "address=$(echo "$RESP" | jq -r '.mailbox.address')" >> "$GITHUB_OUTPUT"

      - name: Trigger signup with temp email
        run: |
          curl -sS -X POST "$APP_SIGNUP_URL" \
            -H "Content-Type: application/json" \
            -d "{\"email\":\"${{ steps.inbox.outputs.address }}\"}"

      - name: Poll for OTP email
        id: otp
        run: |
          for i in $(seq 1 20); do
            BODY=$(curl -sS -H "Authorization: Bearer $MAILGX_API_KEY" \
              "$MAILGX_BASE_URL/api/v1/messages?mailbox=${{ steps.inbox.outputs.address }}&limit=1" \
              | jq -r '.messages[0].body // empty')
            OTP=$(echo "$BODY" | grep -Eo '[0-9]{4,8}' | head -1)
            if [ -n "$OTP" ]; then
              echo "code=$OTP" >> "$GITHUB_OUTPUT"
              exit 0
            fi
            sleep 3
          done
          echo "OTP email not received" >&2
          exit 1

      - name: Assert OTP captured
        run: test -n "${{ steps.otp.outputs.code }}"

CI/CD best practices

  • Create one disposable inbox per test job — parallel jobs need separate mailboxes.
  • Poll with 2–3 second intervals; allow 15–30 attempts before failing.
  • Use regex to extract 4–8 digit OTP codes from HTML or plain-text bodies.
  • Delete test mailboxes after the run to stay within daily API quotas.
  • Use premium private domains when staging blocks public disposable hostnames.

Read the full walkthrough: How to test OTP flows with MailGX API · Best disposable email for developers

Authentication

All API endpoints require a valid API key. Daily quota depends on your active plan.

Option 1: Authorization Header
Authorization: Bearer rm_live_your_key_here
Option 2: Query Parameter
GET https://mailgx.com/api/v1/mailboxes?apiKey=rm_live_your_key_here

Important: Basic, Regular, and PRO can all use the API, with daily limits of 100, 500, and 10,000 requests respectively (before add-ons).

POST /api/v1/mailboxes

Create a new mailbox or access an existing one.

Request
curl -X POST https://mailgx.com/api/v1/mailboxes \
  -H "Authorization: Bearer rm_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "localPart": "support",
    "domain": "mailgx.com",
    "autoGenerate": false
  }'
Response (201)
{
  "mailbox": {
    "address": "support@mailgx.com",
    "localPart": "support",
    "domain": "mailgx.com",
    "createdAt": "2026-04-18T10:30:00Z",
    "expiresAt": null,
    "persistent": true,
    "ownerId": "user-id",
    "allowReply": true,
    "messageCount": 0,
    "unreadCount": 0,
    "messages": []
  },
  "recreated": false,
  "page": { "limit": 0, "hasMore": false, "nextCursor": null, "total": 0 }
}

Request Body Parameters

FieldTypeRequiredDescription
localPartstringNo*Local part of email (before @). *Required unless autoGenerate is true
domainstringNo*Domain name. *Required unless autoGenerate is true
addressstringNoFull email address (overrides localPart + domain)
autoGeneratebooleanNoAuto-generate random address if true. Default: false

GET /api/v1/mailboxes

List all mailboxes owned by authenticated user.

Request
curl -H "Authorization: Bearer rm_live_your_key" \
  https://mailgx.com/api/v1/mailboxes
Response (200)
{
  "mailboxes": [
    {
      "address": "support@mailgx.com",
      "localPart": "support",
      "domain": "mailgx.com",
      "createdAt": "2026-04-18T10:30:00Z",
      "messageCount": 5,
      "unreadCount": 2
    }
  ]
}

GET /api/v1/mailboxes/[address]

Get detailed information about a specific mailbox including all messages.

Request
curl -H "Authorization: Bearer rm_live_your_key" \
  "https://mailgx.com/api/v1/mailboxes/support@mailgx.com?limit=50"
Response (200)
{
  "address": "support@mailgx.com",
  "messages": [
    {
      "id": "msg-uuid-1",
      "from": "noreply@example.com",
      "subject": "Your verification code",
      "body": "Your code is 482910",
      "receivedAt": "2026-04-18T09:15:00Z",
      "direction": "incoming"
    }
  ]
}

DELETE /api/v1/mailboxes/[address]

Delete a mailbox owned by the authenticated API user.

Request
curl -X DELETE -H "Authorization: Bearer rm_live_your_key" \
  "https://mailgx.com/api/v1/mailboxes/support@mailgx.com"

GET /api/v1/messages

List all messages in a mailbox with pagination — primary endpoint for OTP polling.

Request
curl -H "Authorization: Bearer rm_live_your_key" \
  "https://mailgx.com/api/v1/messages?mailbox=support@mailgx.com&limit=20"

GET /api/v1/messages/[messageId]

Get complete body of a single message.

Request
curl -H "Authorization: Bearer rm_live_your_key" \
  "https://mailgx.com/api/v1/messages/msg-uuid-1?mailbox=support@mailgx.com"

POST /api/v1/reply

Send a reply to the latest incoming message in a mailbox.

Request
curl -X POST https://mailgx.com/api/v1/reply \
  -H "Authorization: Bearer rm_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "mailbox": "support@mailgx.com",
    "body": "Thank you for your inquiry."
  }'

Error Responses

401 Unauthorized
{ "error": "Invalid or expired API key." }
429 Too Many Requests
{ "error": "Daily API limit reached for the Basic plan." }
404 Not Found
{ "error": "Mailbox not found or expired." }

Rate Limiting & Quotas

  • Message body size: Max 10,000 characters
  • Reply length: Max 10,000 characters
  • Messages per request: Max 200
  • Daily API quota: Basic 100 · Regular 500 · PRO 10,000

Share & integrate

Add a link in your project README: https://mailgx.com/api-docs · Postman: https://mailgx.com/mailgx-api.postman_collection.json

Continue exploring: Home — free temp mail · Blog guides · Premium pricing & API limits

Remember: Keep your API key secret. Never commit it to version control.