https://github.com/kmulvey/mailhole

A mock SMTP server and REST API to capture and validate emails sent by your application.
https://github.com/kmulvey/mailhole

cypress playwright testing

Last synced: about 1 month ago
JSON representation

A mock SMTP server and REST API to capture and validate emails sent by your application.

• Host: GitHub
• URL: https://github.com/kmulvey/mailhole
• Owner: kmulvey
• License: mit
• Created: 2025-07-10T15:00:34.000Z (12 months ago)
• Default Branch: main
• Last Pushed: 2025-07-11T20:49:52.000Z (12 months ago)
• Last Synced: 2025-07-11T21:30:48.833Z (12 months ago)
• Topics: cypress, playwright, testing
• Language: Go
• Homepage:
• Size: 66.4 KB
• Stars: 1
• Watchers: 0
• Forks: 0
• Open Issues: 0
• Metadata Files:
  • Readme: README.md
  • License: LICENSE

Awesome Lists containing this project

README

          
# mailhole

A mock SMTP server and REST API to capture and validate emails sent by your application. 

## REST API

| Method | Path                                         | Description                        |

|--------|----------------------------------------------|------------------------------------|

| GET    | `/emails/:recipient/messages`                | List all messages for recipient    |

| GET    | `/emails/:recipient/messages/:which`         | Get a specific message (by index, "first", or "last") |

| GET    | `/emails/:recipient/stream`                  | WebSocket stream for new messages  |

## Database Setup

1. **Start postgres and mailhole**

   ```sh

   docker compose up --build

2. **Install Atlas**

   [Install Atlas](https://atlasgo.io/getting-started/install) or run:

   ```sh

   curl -sSf https://atlasgo.sh | sh

3. **Create the database**

   ```sh

   psql -U postgres -c 'CREATE DATABASE mailhole;'

4. **Apply migrations**

   ```sh

   atlas migrate apply --dir file://db/migrations --url postgres://mailhole:mailhole@localhost:5432/mailhole?sslmode=disable

5. **(Optional) Baseline an existing database**

   ```sh

   atlas migrate apply --dir file://db/migrations --url postgres://mailhole:mailhole@localhost:5432/mailhole?sslmode=disable --baseline 20250709231344

## Try it

1. **In a different terminal, start the websocket**

   [Install wscat](https://github.com/websockets/wscat) or run:

   ```sh

   wscat -c ws://localhost:8080/emails/kevin@example.com/stream

2. **In a different terminal, send an email**

   ```sh

    curl -s "smtp://localhost:2525"   --mail-from "verify@example.com"   --mail-rcpt "kevin@example.com"   --upload-file testdata/email.txt

3. **Retrieve the last email to that address**

   ```sh

    curl -s "http://localhost:8080/emails/kevin@example.com/messages/last" | jq

    {

      "id": 307,

      "sender": "verify@example.com",

      "recipient": "kevin@example.com",

      "subject": "PaperlessPost Verification email",

      "body": "Please click here:\nhttps://example.com\nhttps://example.com/wedding\nhttps://example.com/pricing",

      "links": [

        "https://example.com",

        "https://example.com/wedding",

        "https://example.com/pricing"

      ],

      "received_at": "2025-07-11T19:57:33.460239Z"

    }