Emails

Email object

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "toAddress": "signup@acme.mailoven.com",
  "fromAddress": "noreply@example.com",
  "fromName": "Example App",
  "subject": "Verify your email",
  "body": "<p>Click the link to verify...</p>",
  "receivedAt": "2025-03-15T10:30:00.000Z",
  "read": false
}

Field	Type	Description
id	string	UUID of the email
toAddress	string	Full recipient address
fromAddress	string	Sender email address
fromName	string	Sender display name
subject	string | null	Email subject line
body	string | null	Sanitized HTML body
receivedAt	string	ISO 8601 timestamp
read	boolean	Whether the email has been viewed in the UI

List emails

GET /api/v1/emails?to=<local-part>

Query parameters

Parameter	Required	Type	Description
to	Yes	string	Local part of the inbox address (e.g. signup for signup@acme.mailoven.com)
subject	No	string	Filter by subject (case-insensitive substring match)
body	No	string	Filter by body content (case-insensitive substring match)
search	No	string	Full-text search across subject, sender, and body
limit	No	number	Max results to return (1–10, default 10)
since	No	number	Unix timestamp — only return emails received after this time

TIP

Only one of subject, body, or search can be specified per request.

Example

# List recent emails for the "signup" inbox
curl -H "Authorization: Bearer mo_your_key" \
  "https://mailoven.com/api/v1/emails?to=signup"

# Search for emails with "verification" in the subject
curl -H "Authorization: Bearer mo_your_key" \
  "https://mailoven.com/api/v1/emails?to=signup&subject=verification"

# Get emails received in the last 60 seconds
curl -H "Authorization: Bearer mo_your_key" \
  "https://mailoven.com/api/v1/emails?to=signup&since=$(date -v-60S +%s)"

Response

[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "toAddress": "signup@acme.mailoven.com",
    "fromAddress": "noreply@example.com",
    "fromName": "Example App",
    "subject": "Verify your email",
    "body": "<p>Click the link...</p>",
    "receivedAt": "2025-03-15T10:30:00.000Z",
    "read": false
  }
]

Errors

Status	Error
400	'to' is required.
400	Invalid local part. Only alphanumeric characters and _-+. are allowed.
400	Only one of subject, search, or body may be specified.

Get email

GET /api/v1/emails/:id

Returns a single email by ID.

Example

curl -H "Authorization: Bearer mo_your_key" \
  "https://mailoven.com/api/v1/emails/550e8400-e29b-41d4-a716-446655440000"

Response

Returns the email object.

Status	Error
404	Email not found

Delete email

DELETE /api/v1/emails/:id

Permanently deletes a single email.

Example

curl -X DELETE -H "Authorization: Bearer mo_your_key" \
  "https://mailoven.com/api/v1/emails/550e8400-e29b-41d4-a716-446655440000"

Response

Returns 204 No Content on success.

Status	Error
404	Email not found