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 -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
# 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"
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/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.
Authorization: Bearer rm_live_your_key_here
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.
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
}'{
"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
| Field | Type | Required | Description |
|---|---|---|---|
localPart | string | No* | Local part of email (before @). *Required unless autoGenerate is true |
domain | string | No* | Domain name. *Required unless autoGenerate is true |
address | string | No | Full email address (overrides localPart + domain) |
autoGenerate | boolean | No | Auto-generate random address if true. Default: false |
GET /api/v1/mailboxes
List all mailboxes owned by authenticated user.
curl -H "Authorization: Bearer rm_live_your_key" \ https://mailgx.com/api/v1/mailboxes
{
"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.
curl -H "Authorization: Bearer rm_live_your_key" \ "https://mailgx.com/api/v1/mailboxes/support@mailgx.com?limit=50"
{
"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.
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.
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.
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.
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
{ "error": "Invalid or expired API key." }{ "error": "Daily API limit reached for the Basic plan." }{ "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.