Messages

Get Messages

Retrieve message metadata from a temporary email account inbox. Supports both Mail.tm and MoeMail providers.

Endpoint

GET /api/v1/temp-mail/messages

Authentication

Requires API Key in header:

Authorization: Bearer your_api_key_here

Query Parameters

Parameter	Type	Required	Description
`accountId`	string	No	The temporary email account ID. Required if `email` is not provided
`email`	string	No	Account email address. Can be used instead of `accountId` for DB-tracked accounts
`provider`	string	No	Provider type: `mail.tm` or `moemail` (default: `mail.tm`)
`messageId`	string	No	Message ID to fetch full detail from this query-style endpoint
`msgId`	string	No	Alias of `messageId`

Response

Success Response (200 OK)

{
  "success": true,
  "account": {
    "id": "account_123abc",
    "address": "[email protected]",
    "token": "eyJhbGciOi..."
  },
  "messages": [
    {
      "id": "msg_123abc",
      "from": {
        "name": "Sender Name",
        "address": "[email protected]"
      },
      "subject": "Welcome Email",
      "intro": "This is a preview of the message...",
      "createdAt": "2026-04-20T12:00:00.000Z",
      "seen": false
    }
  ],
  "count": 1
}

Error Responses

400 Bad Request - Missing accountId/email

{
  "error": "accountId or email required"
}

401 Unauthorized - Invalid API key or account not found

{
  "error": "Invalid API key"
}

500 Internal Server Error

{
  "error": "Failed to fetch messages"
}

Features

Automatic Database Storage: All messages are automatically saved to the database
Statistics Tracking: New messages increment the global message counter
Duplicate Prevention: Messages are upserted to prevent duplicates
Multi-Provider Support: Works with both Mail.tm and MoeMail
API Usage Tracking: All requests are tracked for analytics

Example Usage

cURL

curl -X GET "https://your-domain.com/api/v1/temp-mail/messages?accountId=abc123&provider=mail.tm" \
  -H "Authorization: Bearer your_api_key_here"

cURL by Email

curl -X GET "https://your-domain.com/api/v1/temp-mail/[email protected]&provider=moemail" \
  -H "Authorization: Bearer your_api_key_here"

cURL Detail by Email + Message ID

curl -X GET "https://your-domain.com/api/v1/temp-mail/[email protected]&provider=moemail&messageId=msg_123abc" \
  -H "Authorization: Bearer your_api_key_here"

POST Body Lookup

Use this when your client only stores the email address and not the generated account ID.

curl -X POST "https://your-domain.com/api/v1/temp-mail/messages" \
  -H "Authorization: Bearer your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "provider": "moemail"
  }'

To fetch one full message detail with the same body style:

curl -X POST "https://your-domain.com/api/v1/temp-mail/messages" \
  -H "Authorization: Bearer your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "provider": "moemail",
    "messageId": "msg_123abc"
  }'

JavaScript (Fetch)

const response = await fetch(
  "/api/v1/temp-mail/messages?accountId=abc123&provider=moemail",
  {
    headers: {
      Authorization: "Bearer your_api_key_here",
    },
  },
);

const data = await response.json();
console.log(`Received ${data.count} messages`);

Python

import requests

headers = {
    'Authorization': 'Bearer your_api_key_here'
}

params = {
    'accountId': 'abc123',
    'provider': 'mail.tm'
}

response = requests.get(
    'https://your-domain.com/api/v1/temp-mail/messages',
    headers=headers,
    params=params
)

data = response.json()
print(f"Received {data['count']} messages")

Notes

Messages are automatically saved to the database for persistence
The messagesReceived statistic is incremented for each new message
For Mail.tm accounts, the token is retrieved from the database
MoeMail accounts don't require tokens
Messages are returned in the order received from the provider
email lookup only works for accounts stored in Devora database under the API key owner. If the email is not found in DB, the API returns 404.

Get Account Messages

Retrieve messages for an account using the account-scoped endpoint. This endpoint auto-detects Mail.tm or MoeMail from the stored account.

Endpoint

GET /api/v1/temp-mail/accounts/{accountId}/messages

Response

Returns an array of message metadata from the provider.

[
  {
    "id": "msg_123abc",
    "from": "[email protected]",
    "subject": "Welcome Email",
    "createdAt": "2026-04-20T12:00:00.000Z"
  }
]

Example Usage

curl -X GET "https://devora.my.id/api/v1/temp-mail/accounts/ACCOUNT_ID/messages" \
  -H "Authorization: Bearer your_api_key_here"

Use this endpoint to get messageId values before requesting full message content.

Get Message Detail

Retrieve full message content, including HTML/text body. Supports both Mail.tm and MoeMail providers.

This is the endpoint to use when you need the same full message body displayed in the Temp Mail UI.

Endpoint

GET /api/v1/temp-mail/accounts/{accountId}/messages/{messageId}

Response

Mail.tm / MoeMail Detail Response (200 OK)

{
  "id": "msg_123abc",
  "from": {
    "name": "Sender Name",
    "address": "[email protected]"
  },
  "subject": "Welcome Email",
  "text": "Plain text content...",
  "html": ["<p>HTML content...</p>"],
  "createdAt": "2026-04-20T12:00:00.000Z"
}

MoeMail HTML Response Example

MoeMail may return html from the upstream provider as a string. Devora normalizes it into an array so clients can handle Mail.tm and MoeMail with the same shape.

{
  "id": "moe_msg_123",
  "from": {
    "name": "Devora",
    "address": "[email protected]"
  },
  "subject": "Verify your account",
  "text": "Your verification code is 123456",
  "html": [
    "<div><h1>Verify your account</h1><p>Your verification code is <strong>123456</strong></p></div>"
  ],
  "createdAt": "2026-04-20T12:00:00.000Z"
}

Example Usage

curl -X GET "https://devora.my.id/api/v1/temp-mail/accounts/ACCOUNT_ID/messages/MESSAGE_ID" \
  -H "Authorization: Bearer your_api_key_here"

Recommended Flow

Create a MoeMail account with POST /api/v1/temp-mail/accounts and body { "provider": "moemail" }.
Fetch inbox metadata with GET /api/v1/temp-mail/accounts/{accountId}/messages.
Pick a message id from the inbox response.
Fetch full HTML/text content with GET /api/v1/temp-mail/accounts/{accountId}/messages/{messageId}.

Notes

Mail.tm detail is fetched with the stored account token.
MoeMail detail is fetched through the MoeMail provider API and normalized so html is returned as an array, matching the UI format.
Account ownership is verified against the API key user before fetching provider data.
The query-style endpoint GET /api/v1/temp-mail/messages can return inbox metadata or full detail when messageId/msgId is provided.
POST /api/v1/temp-mail/messages accepts the same lookup fields in JSON body: accountId, email, provider, and optional messageId/msgId.

On this page