I use Mailpit to capture email while developing CFML applications locally. It works great, but I don’t necessarily need it running all the time. Since I already use CommandBox to start and stop my local ColdFusion server, I wanted Mailpit to follow the same lifecycle.
Fortunately, CommandBox server scripts make this straightforward. When the CommandBox server starts, it can start Mailpit. When the server stops, it can stop Mailpit as well.
Prerequisites
This example is for macOS and assumes Mailpit was installed with Homebrew:
brew install mailpitYou can test Mailpit manually with:
brew services start mailpit
brew services stop mailpitBy default, Mailpit provides:
- A web interface at http://localhost:8025
- An SMTP server on
localhost:1025 - A readiness endpoint at http://localhost:8025/readyz
CommandBox server lifecycle scripts
CommandBox supports server-specific scripts in server.json. Among the available lifecycle events are:
onServerStart, which runs while the server is startingonServerStop, which runs before the server stops
Add the following top-level scripts object to the CommandBox server configuration:
{
"scripts": {
"onServerStart": "!brew services start mailpit",
"onServerStop": "!brew services stop mailpit"
}
}The ! prefix tells CommandBox to execute a native operating-system command.
If CommandBox cannot find Homebrew in its PATH, use the full path to the executable. On an Apple Silicon Mac, that will commonly be /opt/homebrew/bin/brew:
{
"scripts": {
"onServerStart": "!/opt/homebrew/bin/brew services start mailpit",
"onServerStop": "!/opt/homebrew/bin/brew services stop mailpit"
}
}On an Intel Mac, Homebrew is commonly located at /usr/local/bin/brew. Run which brew in Terminal to confirm the correct path.
Wait until Mailpit is ready
Starting the Homebrew service does not necessarily mean Mailpit is ready to accept requests at that exact instant. Mailpit provides /readyz for checking its readiness. A successful request returns an HTTP 200 response.
We can make the startup script check that endpoint once per second for up to 20 seconds:
{
"scripts": {
"onServerStart": [
"!brew services start mailpit",
"!for i in {1..20}; do curl -fsS http://127.0.0.1:8025/readyz && exit 0; sleep 1; done; echo 'Mailpit failed to become ready' >&2; exit 1"
],
"onServerStop": "!brew services stop mailpit"
}
}This script:
- Starts Mailpit through Homebrew.
- Checks the Mailpit readiness endpoint.
- Continues as soon as Mailpit responds successfully.
- Returns an error if Mailpit does not become ready within 20 seconds.
You can also check Mailpit manually at any time:
curl -fsS http://127.0.0.1:8025/readyzTo inspect the Homebrew service state instead, run:
brew services info mailpitShow Mailpit’s status on a local home page
My CommandBox server hosts several local applications, so I have a simple home page that links to each application and development resource. I wanted its Mailpit card to show whether Mailpit was online.
When Mailpit is stopped, the card displays a red Offline badge:
When Mailpit is available, it displays a green Online badge:
First, check the readiness endpoint near the beginning of the CFML page, before the HTML output:
<cfset mailpitOnline = false>
<cftry>
<cfhttp
url="http://127.0.0.1:8025/readyz"
method="GET"
timeout="2"
result="mailpitHealth">
<cfset mailpitOnline = val(mailpitHealth.statusCode) eq 200>
<cfcatch type="any">
<cfset mailpitOnline = false>
</cfcatch>
</cftry>The default value is false. If Mailpit responds with HTTP status 200, it changes to true. A timeout or connection error is caught so an unavailable Mailpit service does not cause the home page itself to fail.
The two-second timeout also prevents the check from delaying the page for too long.
Next, use that value to set the card’s border and status badge:
<div class="col-6 col-md-4 col-lg-3">
<a href="http://localhost:8025" class="text-decoration-none" target="_blank">
<div class="card h-100 shadow-sm <cfif mailpitOnline>border-success<cfelse>border-danger</cfif>">
<div class="card-body text-center">
<h5 class="card-title text-secondary">
Mailpit
<cfif mailpitOnline>
<span class="badge text-bg-success align-middle"
style="font-size: 0.6rem;">Online</span>
<cfelse>
<span class="badge text-bg-danger align-middle"
style="font-size: 0.6rem;">Offline</span>
</cfif>
</h5>
</div>
</div>
</a>
</div>This example uses Bootstrap 5 classes for the card, border, and badge styling.
Putting it all together
The final CommandBox configuration is:
"scripts": {
"onServerStart": [
"!brew services start mailpit",
"!for i in {1..20}; do curl -fsS http://127.0.0.1:8025/readyz && exit 0; sleep 1; done; echo 'Mailpit failed to become ready' >&2; exit 1"
],
"onServerStop": "!brew services stop mailpit"
}Now Mailpit starts along with the CommandBox server, its readiness is verified, and the local home page indicates whether it is online. When the CommandBox server is stopped normally, Mailpit is stopped as well.
A few things to keep in mind
- The stop hook runs when the server is stopped through CommandBox. It cannot run if CommandBox is force-terminated or the computer shuts down unexpectedly.
- Homebrew services are user-wide. If several CommandBox servers or other applications share the same Mailpit instance, stopping one server could stop Mailpit while something else is using it.
- If one CommandBox server hosts several applications, put the scripts in that server’s shared configuration. Mailpit will then follow the lifecycle of the entire server rather than any single application.
- The status badge reflects Mailpit’s state when the CFML page is rendered. Refresh the page to update it.
That’s it. Mailpit is available when the local development server is running and gets out of the way when development is finished.
