API Reference
Base path: /api/v1. All responses are JSON. All IDs are ULIDs (time-sortable, globally unique).
The full OpenAPI 3.1 spec is also served at runtime at GET /api/v1/openapi.yaml.
REST and WebSocket API for RustMail — a self-hosted SMTP mail catcher. All IDs are ULIDs (time-sortable). All timestamps are ISO 8601 UTC. Base path: /api/v1
Servers
List messages
Returns messages ordered by created_at descending (newest first). Use limit and offset for pagination. total reflects the count before pagination is applied.
Parameters
Query Parameters
Full-text search query (matches subject, body, sender, recipients)
Maximum number of results to return
1100050Number of results to skip (for pagination)
00Responses
Paginated list of message summaries
Delete all messages
Get a single message with full body
Responses
Full message including parsed body fields
Delete a single message
Update message fields
Request Body
Responses
Updated message summary
Download raw RFC 822 message source
List attachments for a message (metadata only)
Responses
List of attachment metadata
Download an attachment
Get an inline image by Content-ID
Returns the inline image matching the given Content-ID. Used by the HTML preview to resolve cid: references. Only serves image/* types; falls back to application/octet-stream otherwise.
Responses
Inline image content with appropriate Content-Type and immutable cache headers.
Export a message as EML or JSON
Parameters
Query Parameters
eml returns the raw RFC 822 bytes as a downloadable file. json returns a JSON representation of the full message.
"eml""json"Responses
Exported message. Content-Type is message/rfc822 for eml and application/json for json.
Get email authentication results
Parses authentication-related headers from the raw message and returns structured DKIM, SPF, DMARC, and ARC results. Reads Authentication-Results, DKIM-Signature, Received-SPF, and ARC-Authentication-Results headers. Does not perform cryptographic validation — it displays what upstream mail servers have already verified.
Responses
Parsed authentication results
Assert message count matches constraints
Returns 200 OK when the number of messages matching the given filters satisfies the min/max bounds. Returns 417 Expectation Failed otherwise. Designed for use in CI pipelines with curl -f. If neither min nor max is provided, the assertion always passes and the response contains the raw count.
Parameters
Query Parameters
Minimum number of matching messages (inclusive)
0Maximum number of matching messages (inclusive)
0Filter by subject substring (case-insensitive)
Filter by sender address substring (case-insensitive)
Filter by recipient address substring (case-insensitive)
Responses
Assertion passed
WebSocket real-time event stream
Upgrade to a WebSocket connection to receive real-time inbox events. The server sends JSON text frames. Clients do not need to send frames (ping/pong is handled at the protocol level).
Event types:
| type | data | |---|---| | message:new | MessageSummary object | | message:delete | { "id": "<ulid>" } | | message:read | { "id": "<ulid>", "is_read": true \| false } | | message:starred | { "id": "<ulid>", "is_starred": true \| false } | | message:tags | { "id": "<ulid>", "tags": ["tag1", "tag2"] } | | messages:clear | (no data field) |
Responses
Switching Protocols — WebSocket handshake successful