Postie: Development Email SMTP Server for VS Code

Postie is a Visual Studio Code extension that provides a development email SMTP server using Nodemailer smtp-server. It allows developers to catch and inspect emails sent by their applications during development, all within the VS Code environment.

Postie also supports Cursor for MCP tooling, so you can use the same email inspection and screenshot workflows in Cursor after setup.

Note: This extension is designed for development purposes only. Do not use it in production environments.

Features

Integrated SMTP server using Nodemailer smtp-server
Export emails as .eml files
Open email source in your editor
HTML content preview with responsive design modes (Mobile/Tablet/Desktop)
MCP server integration for VS Code chat/tools: list emails, fetch details, run compatibility checks, and capture screenshots
Screenshot generation via Playwright (Chromium) with predefined device presets (mobile/tablet/desktop)
MCP screenshot resources exposed as postie://screenshots//.png

Installation

Open VS Code
Go to the Extensions view (Ctrl+Shift+X)
Search for "Postie"
Click Install

Alternatively, run the following command in VS Code's quick open (Ctrl+P):

ext install Postie.postie

Usage

Start the Postie SMTP server by clicking the Postie icon in the Activity Bar.
Configure your application to send emails to localhost on the port specified in the Postie config.
View incoming emails in the Postie section located in the sidebar

Postie Welcome screen

Postie will store emails in your vscode until you delete them. You can export emails as .eml files or open the email source in your editor.

When previewing email content, links can be opened in your default web browser by clicking on them with Cmd (on macOS) or Ctrl (on Windows).

For more information, see the Postie Integration Guide.

For MCP and VS Code chat integration, see the bundled MCP_VSCODE_GUIDE.md. Postie also exposes an optional MCP server that provides tools like list_emails, get_email, check_email_compatibility, and capture_email_screenshot when running in a VS Code build that exposes the MCP APIs.

Configuration

To customize Postie for your development environment, you can adjust the following settings in your VS Code settings.json file:

postie.smtpServerPort: The port number for the SMTP server. Default is 587.
postie.smtpUsername: Username for SMTP server authentication. Default is "postie".
postie.smtpPassword: Password for SMTP server authentication. Default is "postie".
postie.maxStoredEmailsCount: The maximum number of emails Postie will store before older emails are deleted. Default is 100.
postie.maxEmailSize: Maximum size of an email in bytes. The default is 1048576 (1MB).
postie.showNewEmailNotification: Set to true to show a notification when a new email arrives. Default is true.
postie.runServerOnStartup: Set to true to automatically start the SMTP server when VS Code starts. Default is true.
postie.allowExternalMails: Set to true to allow receiving emails from external sources. This is useful for testing emails sent from external sources. Default is false.

You can modify these settings to fit your needs. For example, to change the SMTP server port and the maximum email size, add the following lines to your settings.json:

{
  "postie.smtpServerPort": 587,
  "postie.maxEmailSize": 2097152
}

To enable MCP screenshot presets and compatibility clients, extend your settings like this:

{
  "postie.smtpServerPort": 587,
  "postie.maxEmailSize": 2097152,
  "postie.screenshotPresets": ["iphone-14-pro-max", "pixel-7", "ipad-air"],
  "postie.compatibilityClients": [
    "apple-mail.ios",
    "gmail.ios",
    "outlook.windows"
  ]
}

Gotchas

Outlook not rendering EML files correctly on Windows: CR LF EML Export Issue: If you encounter issues with CR LF line endings in EML exports, use the "Change File Encoding" feature in Visual Studio Code. You can find this option at the bottom of the VS Code window. Change the encoding to "Windows (CRLF)" to fix the issue.
MCP server availability: The MCP features require a VS Code build that exposes the MCP APIs (Postie checks for this at runtime). If your VS Code build does not expose the MCP API, Postie will warn and MCP tools/resources will not be registered.
Screenshots require Playwright/Chromium: If you plan to use capture_email_screenshot, install Playwright's Chromium runtime (npx playwright install chromium) and run on a platform that supports Playwright.

Contributing

We welcome contributions to Postie! Please check out our contributing guidelines for more information on how to get started.

Development Setup

To set up a development environment for contributing to the Postie extension, follow these steps:

Clone the Repository

First, clone the repository to your local machine using Git:
Install Dependencies

Navigate to the cloned directory and install the necessary dependencies using npm:
```
npm install
```
Prerequisites
- Node.js 18 or newer (some newly added dependencies require Node 18+)
- npm (or yarn)
- Playwright (only required if you plan to use screenshot capture features)
Install Playwright's Chromium runtime when you need to capture screenshots:
```
npx playwright install chromium
```
Open in VS Code

Open the cloned Postie directory in Visual Studio Code:
```
code .
```
Run the Extension in Development Mode

In VS Code, press F5 to open a new VS Code window with the Postie extension running in development mode. This allows you to test your changes in a real-world scenario.

Note: the build script (esbuild.js) now includes an MCP server bundle (out/mcpServer.js). Use npm run watch to watch and rebuild the extension, webview, and MCP server during development.
Making Changes

Make your desired changes to the code. You can debug the extension by setting breakpoints in the VS Code editor.
Submit a Pull Request

Once you're satisfied with your changes, commit your changes, push them to your fork, and submit a pull request to the main Postie repository.

License

This project is licensed under the MIT License.

Postie