Mailtrap for Craft CMS

This plugin provides a Mailtrap integration for Craft CMS. Mail is sent through the Mailtrap Email API over HTTPS, not SMTP.

Requirements

This plugin requires Craft CMS 4.0.0+ or 5.0.0+, and PHP 8.0.2+.

Note for Craft 4: Craft 4 pins twig/twig to a release that carries security advisories, and Composer 2.10 refuses to install such a package by default. That blocks creating a new Craft 4 project, before this plugin is involved at all. Adding the plugin to an existing Craft 4 site is unaffected: Composer keeps the version already in composer.lock and only prints a warning. This is a constraint in Craft itself, not in this plugin.

Installation

Not published yet. The plugin is not on Packagist or in the Craft Plugin Store so far, so Composer cannot find it by name alone. Until it is, install it from its Git repository as described under “With Composer” below.

From the Plugin Store

Not available yet. Once the plugin is approved, you will be able to go to the Plugin Store in your project’s Control Panel, search for “Mailtrap” and click the “Install” button in its modal window.

With Composer

First tell Composer where the plugin lives, by adding its repository to your project’s composer.json:

"repositories": [
  {
    "type": "vcs",
    "url": "https://github.com/yournextagency/craft-mailtrap.git"
  }
]

Composer then reads the plugin’s tags straight from GitHub and installs the newest one. The repository is public, so no token or SSH key is involved.

Then open your terminal and run the following commands:

# go to the project directory
cd /path/to/my-project.test

# tell Composer to load the plugin
composer require yournextagency/craft-mailtrap

# tell Craft to install the plugin
./craft install/plugin mailtrap

Add :1.0.0 to the package name to pin an exact release instead of taking the newest tag.

With DDEV

Composer and Craft both run inside the container, so prefix the commands:

ddev composer require yournextagency/craft-mailtrap
ddev craft install/plugin mailtrap

Once the plugin is published on Packagist, the repositories entry becomes unnecessary and can be removed; the commands above keep working unchanged.

Setup

Once Mailtrap is installed, go to Settings → Email and change the “Transport Type” setting to “Mailtrap”. Enter the API token for your sending domain and click Save.

Tokens are created per sending domain, and a token needs admin permission on that domain to send. The full token is shown only once, when it is created or reset — so put it in your .env file right away.

Setting	Required	Description
API Token	Yes	The API token for your sending domain.
Endpoint	No	Defaults to https://send.api.mailtrap.io. Set it to https://bulk.api.mailtrap.io to send over the bulk stream.
Inbox ID	No	When set, mail is delivered to that Mailtrap sandbox inbox instead of to real recipients.

Endpoint and Inbox ID describe different destinations, so set one or the other, not both.

Tip: All three settings can be set to environment variables. See Environmental Configuration in the Craft docs to learn more about that.

Sandbox

Set Inbox ID to have Craft deliver into a Mailtrap inbox rather than to real recipients. That is useful on staging, where you want to see the mail your site sends without anyone receiving it.

Because the setting accepts an environment variable, one plugin configuration covers every environment:

# .env on staging — mail lands in inbox 1234567
MAILTRAP_TOKEN=your-token
MAILTRAP_INBOX_ID=1234567

# .env in production — mail is delivered for real
MAILTRAP_TOKEN=your-token
MAILTRAP_INBOX_ID=

An unset or empty MAILTRAP_INBOX_ID means live sending.

Trademarks

Mailtrap is a trademark of its owner. This plugin is an unofficial integration and is not affiliated with, endorsed by, or sponsored by Mailtrap.