The challenge is this: We have a Laravel thing in development that needs to receive an email and take an action based on that email. Specifically, create an entry in the project's database. It's not too much of a problem in the grand scheme of things - once it's live we have email workers that will do it, make the email hit an API endpoint containing the data we need, and then the controller handles the rest.
But for now, while in development it's just on our local machines and we need to be able to test it. It doesn't look like there's anything out of the box that does it, but surely it's not actually that hard? Anyway. What has resulted is me finding a way to do it, with a nagging feeling at the back of my mind that I'm missing something really obvious.
Here's what I did.
Firstly, I made sure that the Laravel install knew what it was doing by creating an API endpoint. For testing of the mail server I just ran an empty Laravel 11 install, and made a create_user endpoint
php artisan install:api
Then turning to the routes file, I added a route to the create_user endpoint (in routes/api.php)
Route::post('/create-user', [UserController::class, 'createUser']);
Pretty straight forward to start with. In fact the whole Laravel side of stuff was like that. The UserConroller createUser method was just a simple insert into the database, after a quick check to see if the user already existed. To find out what we were receiving from the email I also logged the request()->json to the log file.
Then the localhost email set up. I searched around for an easy gui or something to install, MailHog and things like that were mentioned but I didn't want to mess around with the configs on all that. I just wanted to send an email to myself. First thing I did was test the sending of an email:
echo "Testing" | mail -s "Testing email" iamalsoandy@localhost
All ok so far, the email is in my mail log, mail in the command line confirmed that.
I created a little script that handles the incoming email and sends it to the Laravel endpoint. I created a file process-email.sh, saved it somewhere or other (for this testing I just put it in the project folder, but something like /usr/local/bin would be better), making it executable with
chmod +x process-email.sh
The script looks like this - a heads up, I'm not a bash expert, or really even a Bash Novice, so this is probably not the best way to do it, but it works:
#!/bin/bash
# Get the email content
EMAIL_CONTENT=$(cat)
# Extract some fields from the email_content
SUBJECT=$(echo "$EMAIL_CONTENT" | grep -m 1 "^Subject:" | sed 's/Subject: //')
FROM=$(echo "$EMAIL_CONTENT" | grep -m 1 "^From:" | sed 's/From: //')
TO=$(echo "$EMAIL_CONTENT" | grep -m 1 "^To:" | sed 's/To: //')
DATE=$(echo "$EMAIL_CONTENT" | grep -m 1 "^Date:" | sed 's/Date: //')
# Extract the body of the email
BODY=$(echo "$EMAIL_CONTENT" | sed '1,/^$/d')
ESCAPED_BODY=$(echo "$BODY" | jq -R .)
# Trigger API call and send the data
curl -X POST http://apitest.test/api/create-user/ \
-H "Content-Type: application/json" \
-d "{"subject":"$SUBJECT","body":"$ESCAPED_BODY",
"from":"$FROM","to":"$TO","date":"$DATE"}"
Next I want to intercept those emails and do something else. The Postfix config file, /etc/postfix/main.cf tells me this:
# The mailbox_command parameter specifies the optional external
# command to use instead of mailbox delivery. The command is run as
# the recipient with proper HOME, SHELL and LOGNAME environment settings.
# Exception: delivery for root is done as $default_user.
Which probably means I shouldn't do something like this:
mailbox_command = /path/to/my/script/process-email.sh
But I did.
When the postfix config is changed, it needs restating with sudo postfix restart and then it works!
So now any time my local mailbox receives an email it triggers the script, rather than going to my mailbox. I should probably do something so that the mail still gets handled in the regular way but for now, yeah, this is fine. When I rerun the mail -s instead of going to the mailbox, it curls the api, the user is created, and the log file is updated.
One final thing, just to make the test a bit more lifelike I wanted to be able to email from a GUI rather than the command line so I installed Thunderbird, Trying to get the MacOS Mail App to work with localhost was a bit of a faff - it kept telling me I had to use a password, and asking me questions I didn't want to answer. Thunderbird just let me set up the smtp server using username@localhost and no password, and it works. I create an email with iamalso@localhost as the recipient and the process is tested.
As is probably clear, and I hope I've acknowledged, I'm not an expert in bash and a lot of what I've done here. But for today's testing it was worked a treat.