API docs by Redocly

ACMEmailtrap API (0.4.1)

Download OpenAPI specification:

License: Apache-2.0

REST API of ACMEmailtrap, the email trap for testing ACMEsuite mail flows. Catches SMTP, stores per recipient, serves IMAP and this API. When login is enabled, all endpoints except /api/auth require an authenticated session.

Mailboxes

List mailboxes

All recipient mailboxes, most-recently-active first; the "Sent" mailbox last.

Responses

Response Schema: application/json
Array
address
string
folder
string
total
integer
unseen
integer
lastReceivedAt
integer <int64>

epoch millis

sent
boolean
label
string or null

Response samples

Content type
application/json
[
  • {
    • "address": "string",
    • "folder": "string",
    • "total": 0,
    • "unseen": 0,
    • "lastReceivedAt": 0,
    • "sent": true,
    • "label": "string"
    }
]

Delete a mailbox and all its messages

path Parameters
mailbox
required
string

Recipient address (URL-encoded), e.g. bob%40kunde.test

Responses

Messages

List messages in a mailbox

Newest first.

path Parameters
mailbox
required
string

Recipient address (URL-encoded), e.g. bob%40kunde.test

Responses

Response Schema: application/json
Array
id
string
from
string
subject
string
receivedAt
integer <int64>
size
integer <int64>
seen
boolean
recipients
Array of strings
mod
string

originating ACMEsuite module (X-ACMEsuite-Module)

snippet
string

Response samples

Content type
application/json
[
  • {
    • "id": "string",
    • "from": "string",
    • "subject": "string",
    • "receivedAt": 0,
    • "size": 0,
    • "seen": true,
    • "recipients": [
      ],
    • "mod": "string",
    • "snippet": "string"
    }
]

Get a message with parsed bodies and attachments

path Parameters
mailbox
required
string

Recipient address (URL-encoded), e.g. bob%40kunde.test

id
required
string

Responses

Response Schema: application/json
id
string
mailbox
string
from
string
subject
string
receivedAt
integer <int64>
size
integer <int64>
seen
boolean
recipients
Array of strings
mod
string
text
string
html
string
Array of objects (Attachment)

Response samples

Content type
application/json
{
  • "id": "string",
  • "mailbox": "string",
  • "from": "string",
  • "subject": "string",
  • "receivedAt": 0,
  • "size": 0,
  • "seen": true,
  • "recipients": [
    • "string"
    ],
  • "mod": "string",
  • "text": "string",
  • "html": "string",
  • "attachments": [
    • {
      }
    ]
}

Delete a single message

path Parameters
mailbox
required
string

Recipient address (URL-encoded), e.g. bob%40kunde.test

id
required
string

Responses

Raw RFC 822 source (.eml)

path Parameters
mailbox
required
string

Recipient address (URL-encoded), e.g. bob%40kunde.test

id
required
string

Responses

Response Schema: message/rfc822
string <binary>

Download one attachment by index

path Parameters
mailbox
required
string

Recipient address (URL-encoded), e.g. bob%40kunde.test

id
required
string
index
required
integer >= 0

Responses

Response Schema: application/octet-stream
string <binary>

Mark a message seen or unseen

path Parameters
mailbox
required
string

Recipient address (URL-encoded), e.g. bob%40kunde.test

id
required
string
Request Body schema: application/json
seen
boolean
Default: true

Responses

Request samples

Content type
application/json
{
  • "seen": true
}

Force-forward a specific message now

Relays via the configured forwarder if forwarding is enabled; otherwise logs a warning.

path Parameters
mailbox
required
string

Recipient address (URL-encoded), e.g. bob%40kunde.test

id
required
string

Responses

Response Schema: application/json
relayed
boolean

Response samples

Content type
application/json
{
  • "relayed": true
}

Compose

Compose and deliver a test message into the trap

The recipients appear as (new) mailboxes; a copy is stored in "Sent".

Request Body schema: application/json
required
from
string
to
required
Array of strings non-empty
subject
string
text
string
html
string

Responses

Response Schema: application/json
id
string

Request samples

Content type
application/json
{
  • "from": "string",
  • "to": [
    • "string"
    ],
  • "subject": "string",
  • "text": "string",
  • "html": "string"
}

Response samples

Content type
application/json
{
  • "id": "string"
}

Forwarding

Force-forward a specific message now

Relays via the configured forwarder if forwarding is enabled; otherwise logs a warning.

path Parameters
mailbox
required
string

Recipient address (URL-encoded), e.g. bob%40kunde.test

id
required
string

Responses

Response Schema: application/json
relayed
boolean

Response samples

Content type
application/json
{
  • "relayed": true
}

Current forwarding configuration

Secret values are never returned.

Responses

Response Schema: application/json
enabled
boolean
forwarderId
string

one of the /api/forward/providers ids

mailboxes
Array of strings

addresses to forward; empty = all

object

forwarder settings keyed by its config schema; secrets blanked on read

Response samples

Content type
application/json
{
  • "enabled": true,
  • "forwarderId": "string",
  • "mailboxes": [
    • "string"
    ],
  • "values": {
    • "property1": "string",
    • "property2": "string"
    }
}

Update forwarding configuration

A blank secret keeps the stored value.

Request Body schema: application/json
required
enabled
boolean
forwarderId
string

one of the /api/forward/providers ids

mailboxes
Array of strings

addresses to forward; empty = all

object

forwarder settings keyed by its config schema; secrets blanked on read

Responses

Response Schema: application/json
enabled
boolean
forwarderId
string

one of the /api/forward/providers ids

mailboxes
Array of strings

addresses to forward; empty = all

object

forwarder settings keyed by its config schema; secrets blanked on read

Request samples

Content type
application/json
{
  • "enabled": true,
  • "forwarderId": "string",
  • "mailboxes": [
    • "string"
    ],
  • "values": {
    • "property1": "string",
    • "property2": "string"
    }
}

Response samples

Content type
application/json
{
  • "enabled": true,
  • "forwarderId": "string",
  • "mailboxes": [
    • "string"
    ],
  • "values": {
    • "property1": "string",
    • "property2": "string"
    }
}

Installed forwarder plugins and their config schemas

Responses

Response Schema: application/json
Array
id
string
displayName
string
kind
string
Enum: "SMTP" "GRAPH" "GOOGLE" "HTTP_API" "WEBHOOK"
Array of objects (ConfigField)

Response samples

Content type
application/json
[
  • {
    • "id": "string",
    • "displayName": "string",
    • "kind": "SMTP",
    • "schema": [
      ]
    }
]

Server

SMTP/IMAP status and live metrics

Responses

Response Schema: application/json
object (SmtpStatus)
object (ImapStatus)
connections
integer
throughputPerMin
integer
forwards
integer <int64>

Response samples

Content type
application/json
{
  • "smtp": {
    • "port": 0,
    • "up": true,
    • "uptimeSec": 0,
    • "received": 0,
    • "errors": 0
    },
  • "imap": {
    • "port": 0,
    • "up": true,
    • "uptimeSec": 0,
    • "sessions": 0,
    • "folders": 0
    },
  • "connections": 0,
  • "throughputPerMin": 0,
  • "forwards": 0
}

Recent tagged event log entries (newest first)

query Parameters
limit
integer [ 1 .. 500 ]
Default: 100

Responses

Response Schema: application/json
Array
time
integer <int64>
tag
string

RECV | SEND | SMTP | IMAP | WARN | ERR

msg
string

Response samples

Content type
application/json
[
  • {
    • "time": 0,
    • "tag": "string",
    • "msg": "string"
    }
]

Dashboard KPIs

Responses

Response Schema: application/json
messages
integer
mailboxes
integer
unread
integer
today
integer

Response samples

Content type
application/json
{
  • "messages": 0,
  • "mailboxes": 0,
  • "unread": 0,
  • "today": 0
}

Search

Full-text search across messages and mailboxes

query Parameters
q
string

Query over subject, sender, body and mailbox address.

limit
integer [ 1 .. 50 ]
Default: 20

Responses

Response Schema: application/json
Array of objects (MailboxInfo)
Array of objects (SearchHit)

Response samples

Content type
application/json
{
  • "mailboxes": [
    • {
      }
    ],
  • "messages": [
    • {
      }
    ]
}

Auth

Login state and available providers

Always accessible so the UI can render a login screen.

Responses

Response Schema: application/json
enabled
boolean
authenticated
boolean
user
string or null
Array of objects (AuthProviderInfo)

Response samples

Content type
application/json
{
  • "enabled": true,
  • "authenticated": true,
  • "user": "string",
  • "providers": [
    • {
      }
    ]
}

Meta

Dashboard KPIs

Responses

Response Schema: application/json
messages
integer
mailboxes
integer
unread
integer
today
integer

Response samples

Content type
application/json
{
  • "messages": 0,
  • "mailboxes": 0,
  • "unread": 0,
  • "today": 0
}

Ports and forwarding summary for the UI

Responses

Response Schema: application/json
smtpPort
integer
smtpEnabled
boolean
imapPort
integer
imapEnabled
boolean
forwardEnabled
boolean
forwardHost
string

Response samples

Content type
application/json
{
  • "smtpPort": 0,
  • "smtpEnabled": true,
  • "imapPort": 0,
  • "imapEnabled": true,
  • "forwardEnabled": true,
  • "forwardHost": "string"
}

Build identity (version, commit, branch)

Responses

Response Schema: application/json
version
string
commit
string
branch
string
buildTime
integer or null <int64>
label
string

e.g. 0.2.0 (a1b2c3d)

Response samples

Content type
application/json
{
  • "version": "string",
  • "commit": "string",
  • "branch": "string",
  • "buildTime": 0,
  • "label": "string"
}