API Feature

REST API for Basic, Regular, and PRO

Full programmatic access to create mailboxes, read messages, and send replies using REST endpoints.

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 /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 10000 requests respectively.

POST /api/v1/mailboxes

Create a new mailbox or access an existing one.

Request

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

Response (201)

{
  "mailbox": {
    "address": "support@mailgx.org",
    "localPart": "support",
    "domain": "mailgx.org",
    "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.

Request

curl -H "Authorization: Bearer rm_live_your_key" \
  https://your-domain.com/api/v1/mailboxes

Response (200)

{
  "mailboxes": [
    {
      "address": "support@mailgx.org",
      "localPart": "support",
      "domain": "mailgx.org",
      "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://your-domain.com/api/v1/mailboxes/support@mailgx.org?limit=50"

Response (200)

{
  "address": "support@mailgx.org",
  "localPart": "support",
  "domain": "mailgx.org",
  "createdAt": "2026-04-18T10:30:00Z",
  "expiresAt": null,
  "persistent": true,
  "allowReply": true,
  "unreadCount": 2,
  "messageCount": 5,
  "messages": [
    {
      "id": "msg-uuid-1",
      "from": "customer@example.com",
      "to": "support@mailgx.org",
      "subject": "Need help with my order",
      "preview": "Hi, I'm having trouble with...",
      "body": "Hi,\n\nI'm having trouble with my recent order...",
      "receivedAt": "2026-04-18T09:15:00Z",
      "direction": "incoming"
    }
  ]
}

Query Parameters

Parameter	Type	Default	Description
`limit`	number	50	Max messages to return (1-200)

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://your-domain.com/api/v1/mailboxes/support@mailgx.org"

Response (200)

{
  "deleted": true,
  "address": "support@mailgx.org"
}

Notes

Rule	Details
Auth	Same API key model as GET and POST v1 mailbox endpoints
Ownership	Only the mailbox owner can delete it
Result	Returns deleted true and the normalized mailbox address
Compatibility	Also supports DELETE /api/v1/mailboxes with address in query or JSON body for worker/client cleanup flows

GET /api/v1/messages/[messageId]

Get complete body of a single message.

Request

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

Response (200)

{
  "id": "msg-uuid-1",
  "from": "customer@example.com",
  "to": "support@mailgx.org",
  "subject": "Need help with my order",
  "body": "Hi,\n\nI'm having trouble with my recent order. The tracking number shows delivered but I haven't received it yet...",
  "preview": "Hi, I'm having trouble with...",
  "receivedAt": "2026-04-18T09:15:00Z",
  "direction": "incoming"
}

Query Parameters

Parameter	Type	Required	Description
`mailbox`	string	Yes	Mailbox address to search in (e.g., support@mailgx.org)

GET /api/v1/messages

List all messages in a mailbox with pagination.

Request

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

Response (200)

{
  "mailbox": "support@mailgx.org",
  "count": 20,
  "total": 45,
  "hasMore": true,
  "nextCursor": "offset_20",
  "messages": [
    {
      "id": "msg-uuid-1",
      "from": "customer@example.com",
      "to": "support@mailgx.org",
      "subject": "Need help",
      "body": "...",
      "preview": "Hi, I'm having trouble...",
      "receivedAt": "2026-04-18T09:15:00Z",
      "direction": "incoming"
    }
  ]
}

Query Parameters

Parameter	Type	Required	Default	Description
`mailbox`	string	Yes	—	Mailbox address (e.g., support@mailgx.org)
`limit`	number	No	50	Messages per page (1-200)
`cursor`	string	No	—	Pagination cursor from previous response

POST /api/v1/reply

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

Request

curl -X POST https://your-domain.com/api/v1/reply \
  -H "Authorization: Bearer rm_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "mailbox": "support@mailgx.org",
    "body": "Thank you for your inquiry. We will look into this and get back to you shortly."
  }'

Response (201)

{
  "success": true,
  "message": {
    "id": "msg-uuid-2",
    "from": "support@mailgx.org",
    "to": "customer@example.com",
    "subject": "Re: Need help with my order",
    "body": "Thank you for your inquiry. We will look into this and get back to you shortly.",
    "preview": "Thank you for your inquiry...",
    "receivedAt": "2026-04-18T10:45:00Z",
    "direction": "outgoing"
  }
}

Request Body Parameters

Field	Type	Required	Description
`mailbox`	string	Yes	Target mailbox address (e.g., support@mailgx.org)
`body`	string	Yes	Reply message body (max 10,000 characters)

Note: Reply is sent to the sender of the latest incoming message in the mailbox.

Error Responses

401 Unauthorized

{ "error": "Invalid or expired API key." }

403 Forbidden

{ "error": "Current plan cannot use this domain." }

429 Too Many Requests

{ "error": "Daily API limit reached for the Basic plan." }

404 Not Found

{ "error": "Mailbox not found or expired." }

400 Bad Request

{ "error": "mailbox query parameter is required" }

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 10000

Common Use Cases

1. Create Mailbox & Wait for Emails

# Create a temporary support email
curl -X POST https://your-domain.com/api/v1/mailboxes \
  -H "Authorization: Bearer rm_live_xxx" \
  -d '{"localPart": "support-ticket-123", "domain": "mailgx.org"}' \
  | jq '.mailbox.address'

# Poll for new messages every 5 seconds
while true; do
  curl -H "Authorization: Bearer rm_live_xxx" \
    "https://your-domain.com/api/v1/messages?mailbox=support-ticket-123@mailgx.org"
  sleep 5
done

2. Auto-Reply to Incoming Messages

# Get latest message
curl -H "Authorization: Bearer rm_live_xxx" \
  "https://your-domain.com/api/v1/messages?mailbox=support@mailgx.org&limit=1" \
  | jq '.messages[0]'

# Send automatic reply
curl -X POST https://your-domain.com/api/v1/reply \
  -H "Authorization: Bearer rm_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "mailbox": "support@mailgx.org",
    "body": "We received your message and will respond within 24 hours."
  }'

3. Export All Messages

# Fetch all messages from a mailbox
curl -H "Authorization: Bearer rm_live_xxx" \
  "https://your-domain.com/api/v1/mailboxes/support@mailgx.org?limit=200" \
  | jq '.messages[] | {from: .from, subject: .subject, body: .body, date: .receivedAt}' \
  > messages.json

Support

For issues or questions about the API, please contact support or check the dashboard for troubleshooting tips.

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