diff --git a/README.md b/README.md index 3a5afa6..ecac5d8 100644 --- a/README.md +++ b/README.md @@ -6,13 +6,13 @@ ![CodeQL](https://github.com/axllent/mailpit/actions/workflows/codeql-analysis.yml/badge.svg) [![Go Report Card](https://goreportcard.com/badge/github.com/axllent/mailpit)](https://goreportcard.com/report/github.com/axllent/mailpit) -Mailpit is a small, fast, low memory, zero-dependency, multi-platform email testing tool & API for developers. +[Mailpit](https://mailpit.axllent.org) is a small, fast, low memory, zero-dependency, multi-platform email testing tool & API for developers. -It acts as an SMTP server, provides a modern web interface to view & test captured emails, and contains an API for automated integration testing. +It acts as an SMTP server, provides a modern web interface to view & test captured emails, and includes an API for automated integration testing. -Mailpit was originally **inspired** by MailHog which is [no longer maintained](https://github.com/mailhog/MailHog/issues/442#issuecomment-1493415258) and hasn't seen active development for a few years now. +Mailpit was originally **inspired** by MailHog which is [no longer maintained](https://github.com/mailhog/MailHog/issues/442#issuecomment-1493415258) and hasn't seen active development or security updates for a few years now. -![Mailpit](https://raw.githubusercontent.com/axllent/mailpit/develop/docs/screenshot.png) +![Mailpit](https://raw.githubusercontent.com/axllent/mailpit/develop/server/ui-src/screenshot.png) ## Features diff --git a/docs/apiv1/Message.md b/docs/apiv1/Message.md deleted file mode 100644 index 8663d4e..0000000 --- a/docs/apiv1/Message.md +++ /dev/null @@ -1,116 +0,0 @@ -# Message - -## Message summary - -Returns a JSON summary of the message and attachments. - -**URL** : `api/v1/message/` - -**Method** : `GET` - -## Response - -**Status** : `200` - -```json -{ - "ID": "d7a5543b-96dd-478b-9b60-2b465c9884de", - "MessageID": "12345.67890@localhost", - "From": { - "Name": "John Doe", - "Address": "john@example.com" - }, - "To": [ - { - "Name": "Jane Smith", - "Address": "jane@example.com" - } - ], - "Cc": [], - "Bcc": [], - "ReplyTo": [], - "Subject": "Message subject", - "Date": "2016-09-07T16:46:00+13:00", - "Tags": ["test"], - "Text": "Plain text MIME part of the email", - "HTML": "HTML MIME part (if exists)", - "Size": 79499, - "Inline": [ - { - "PartID": "1.2", - "FileName": "filename.gif", - "ContentType": "image/gif", - "ContentID": "919564503@07092006-1525", - "Size": 7760 - } - ], - "Attachments": [ - { - "PartID": "2", - "FileName": "filename.doc", - "ContentType": "application/msword", - "ContentID": "", - "Size": 43520 - } - ] -} -``` -### Notes - -- `From` - Name & Address, or null -- `To`, `CC`, `BCC`, `ReplyTo` - Array of Names & Address -- `Date` - Parsed email local date & time from headers -- `Size` - Total size of raw email -- `Inline`, `Attachments` - Array of attachments and inline images. - - ---- -## Attachments - -**URL** : `api/v1/message//part/` - -**Method** : `GET` - -Returns the attachment using the MIME type provided by the attachment `ContentType`. - ---- -## Headers - -**URL** : `api/v1/message//headers` - -**Method** : `GET` - -Returns all message headers as a JSON array. -Each unique header key contains an array of one or more values (email headers can be listed multiple times.) - -```json -{ - "Content-Type": [ - "multipart/related; type=\"multipart/alternative\"; boundary=\"----=_NextPart_000_0013_01C6A60C.47EEAB80\"" - ], - "Date": [ - "Wed, 12 Jul 2006 23:38:30 +1200" - ], - "Delivered-To": [ - "user@example.com", - "user-alias@example.com" - ], - "From": [ - "\"User Name\" \\u003remote@example.com\\u003e" - ], - "Message-Id": [ - "\\u003c001701c6a5a7$b3205580$0201010a@HomeOfficeSM\\u003e" - ], -.... -} -``` - - ---- -## Raw (source) email - -**URL** : `api/v1/message//raw` - -**Method** : `GET` - -Returns the original email source including headers and attachments. diff --git a/docs/apiv1/Messages.md b/docs/apiv1/Messages.md deleted file mode 100644 index 74f3ebd..0000000 --- a/docs/apiv1/Messages.md +++ /dev/null @@ -1,169 +0,0 @@ -# Messages - -List & delete messages. - - ---- -## List - -List messages in the mailbox. Messages are returned in the order of latest received to oldest. - -**URL** : `api/v1/messages` - -**Method** : `GET` - - -### Query parameters - -| Parameter | Type | Required | Description | -|-----------|---------|----------|----------------------------| -| limit | integer | false | Limit results (default 50) | -| start | integer | false | Pagination offset | - - -### Response - -**Status** : `200` - -```json -{ - "total": 500, - "unread": 500, - "messages_count": 50, - "start": 0, - "tags": ["test"], - "messages": [ - { - "ID": "1c575821-70ba-466f-8cee-2e1cf0fcdd0f", - "MessageID": "12345.67890@localhost", - "Read": false, - "From": { - "Name": "John Doe", - "Address": "john@example.com" - }, - "To": [ - { - "Name": "Jane Smith", - "Address": "jane@example.com" - } - ], - "Cc": [ - { - "Name": "Accounts", - "Address": "accounts@example.com" - } - ], - "Bcc": [], - "Subject": "Message subject", - "Created": "2022-10-03T21:35:32.228605299+13:00", - "Tags": ["test"], - "Size": 6144, - "Attachments": 0 - }, - ... - ] -} -``` - -### Notes - -- `total` - Total messages in mailbox -- `unread` - Total unread messages in mailbox -- `messages_count` - Total number of messages in mailbox -- `start` - The offset (default `0`) for pagination -- `Read` - The read/unread status of the message -- `From` - Name & Address, or null if none -- `To`, `CC`, `BCC` - Array of Names & Address -- `Created` - Local date & time the message was received -- `Size` - Total size of raw email in bytes - - ---- -## Delete individual messages - -Delete one or more messages by ID. - -**URL** : `api/v1/messages` - -**Method** : `DELETE` - -### Request - -```json -{ - "ids": ["",""...] -} -``` - -### Response - -**Status** : `200` - - ---- -## Delete all messages - -Delete all messages (same as deleting individual messages, but with the "ids" either empty or omitted entirely). - -**URL** : `api/v1/messages` - -**Method** : `DELETE` - -### Request - -```json -{ - "ids": [] -} -``` - -### Response - -**Status** : `200` - - ---- -## Update individual read statuses - -Set the read status of one or more messages. -The `read` status can be `true` or `false`. - -**URL** : `api/v1/messages` - -**Method** : `PUT` - -### Request - -```json -{ - "ids": ["",""...], - "read": false -} -``` - -### Response - -**Status** : `200` - ---- -## Update all messages read status - -Set the read status of all messages. -The `read` status can be `true` or `false`. - -**URL** : `api/v1/messages` - -**Method** : `PUT` - -### Request - -```json -{ - "ids": [], - "read": false -} -``` - -### Response - -**Status** : `200` diff --git a/docs/apiv1/README.md b/docs/apiv1/README.md deleted file mode 100644 index 83e2429..0000000 --- a/docs/apiv1/README.md +++ /dev/null @@ -1,14 +0,0 @@ -# API v1 - -Mailpit provides a simple REST API to access and delete stored messages. - -If the Mailpit server is set to use Basic Authentication, then API requests must use Basic Authentication too. - -You can view the Swagger API documentation directly within Mailpit by going to https://mailpit.axllent.org/docs/api-v1/. - -The API is split into four main parts: - -- [Messages](Messages.md) - Listing, deleting & marking messages as read/unread. -- [Message](Message.md) - Return message data & attachments -- [Tags](Tags.md) - Set message tags -- [Search](Search.md) - Searching messages diff --git a/docs/apiv1/Search.md b/docs/apiv1/Search.md deleted file mode 100644 index b0af869..0000000 --- a/docs/apiv1/Search.md +++ /dev/null @@ -1,70 +0,0 @@ -# Search - -**URL** : `api/v1/search?query=` - -**Method** : `GET` - -The search returns the most recent matches (default 50). -Matching messages are returned in the order of latest received to oldest. - - -## Query parameters - -| Parameter | Type | Required | Description | -|-----------|---------|----------|----------------------------| -| query | string | true | Search query | -| limit | integer | false | Limit results (default 50) | -| start | integer | false | Pagination offset | - - -## Response - -**Status** : `200` - -```json -{ - "total": 500, - "unread": 500, - "messages_count": 25, - "start": 0, - "messages": [ - { - "ID": "1c575821-70ba-466f-8cee-2e1cf0fcdd0f", - "MessageID": "12345.67890@localhost", - "Read": false, - "From": { - "Name": "John Doe", - "Address": "john@example.com" - }, - "To": [ - { - "Name": "Jane Smith", - "Address": "jane@example.com" - } - ], - "Cc": [ - { - "Name": "Accounts", - "Address": "accounts@example.com" - } - ], - "Bcc": [], - "Subject": "Test email", - "Created": "2022-10-03T21:35:32.228605299+13:00", - "Size": 6144, - "Attachments": 0 - }, - ... - ] -} -``` - -### Notes - -- `total` - Total messages in mailbox (all messages, not search) -- `unread` - Total unread messages in mailbox (all messages, not search) -- `messages_count` - Total number of messages matching search -- `start` - The offset (default `0`) for pagination -- `From` - Singular Name & Address, or null if none -- `To`, `CC`, `BCC` - Array of Name & Address -- `Size` - Total size of raw email in bytes diff --git a/docs/apiv1/Tags.md b/docs/apiv1/Tags.md deleted file mode 100644 index a1e6c6c..0000000 --- a/docs/apiv1/Tags.md +++ /dev/null @@ -1,27 +0,0 @@ -# Tags - -Set message tags. - - ---- -## Update message tags - -Set the tags for one or more messages. -If the tags array is empty then all tags are removed from the messages. - -**URL** : `api/v1/tags` - -**Method** : `PUT` - -### Request - -```json -{ - "ids": ["",""...], - "tags": ["",""] -} -``` - -### Response - -**Status** : `200` diff --git a/docs/screenshot.png b/server/ui-src/screenshot.png similarity index 100% rename from docs/screenshot.png rename to server/ui-src/screenshot.png