Setting Up Email Notification in Jenkins: Get Alerts When Something Goes Wrong
If you’ve ever watched a pipeline finish with an error and then spent half an hour hunting down the culprit, this is for you. I’ve seen build failures sneak into staging without anyone noticing until it’s too late. The trick? A solid email notification that fires the moment a job fails or even when it succeeds so you can stay ahead of the curve.
Why Email Still Matters (and how to make it work)
You might think Slack or Teams is enough, but email survives on every machine and gets into your inbox without extra apps. Plus, Jenkins’ native “Send Mail” plugin gives you granular control over which events trigger an email and who receives them. No third‑party service needed—just the SMTP server you already use for work.
Prerequisites
- A running Jenkins instance (any version that ships with the Mail Extension plugin).
- An SMTP server to relay your messages. That could be Gmail, Office 365, or an internal Exchange server.
- Credentials (username/password or app password) and host/port details from your mail admin.
If you’re not sure about the credentials, ask your IT team; they’ll have them on hand for exactly this reason.
Step‑by‑Step: Configuring Email Notification
1. Install the Mail Extension plugin
Navigate to Manage Jenkins => Manage Plugins and make sure Mail Extension is installed. If you’re using a lightweight installation, it may not be in the default bundle.
> The core “Email Ext” plugin adds custom triggers (e.g., Failure, Unstable) that the plain Mailer can’t handle.
2. Set up Jenkins’ global mail settings
Go to Manage Jenkins => Configure System and scroll to Extended E‑mail Notification (or E‑mail Notification if you’re on an older version). Fill in:
- SMTP server – e.g., smtp.office365.com.
- Default user e‑mail suffix – @yourdomain.com (optional).
- Use SSL or TLS according to your provider.
- Credentials – click Add and paste the credentials you got from IT.
Test the connection at the bottom. If it fails, double‑check port numbers: 587 for TLS, 465 for SSL.
> Why test now? A failed test means nothing will ever get delivered; better catch that early than after a build.
3. Create or edit a job
Open the job you want to monitor. In Post‑build Actions, click Add post‑step => Editable Email Notification (or similar wording).
Configure the recipient list
- Recipient List: dev-team@yourdomain.com, alice@example.com.
You can use environment variables (${BUILD_USER}) if you want to notify only the committer.
> Why explicit? Relying on a broad “Everyone” list floods inboxes and defeats the purpose.
Set triggers
Choose from:
- Failure – default. Fires when result == FAILURE.
- Unstable – for tests that fail but don’t break the build.
- Success – if you want to confirm deployments completed.
Add any custom trigger via Advanced… if needed (e.g., “Always” or “Change”).
Craft the content
The plugin lets you use Groovy templates. A minimal template:
Subject: ${JOB_NAME} #${BUILD_NUMBER} - ${BUILD_STATUS}
Hello team,
${PROJECT_DISPLAY_NAME} finished with status ${BUILD_STATUS}.
Check console output at:
${RUN_URL}
> Why a template? It keeps the message concise and gives you direct links to logs.
4. Optional: Use “Default Subject” and “Content”
If you prefer a more elaborate body (e.g., including test coverage percentages), add Add content under Advanced and paste:
def testCoverage = null
if (currentBuild.rawBuild.getAction(org.jenkinsci.plugins.junit.TestResultAction.class)) {
testCoverage = currentBuild.rawBuild.getAction(org.jenkinsci.plugins.junit.TestResultAction.class).getPercentCovered()
}
return "Build #${BUILD_NUMBER} (${BUILD_STATUS}) – Coverage: ${testCoverage ?: 'N/A'}%\nSee details: ${RUN_URL}"
> Why Groovy? It’s the only way to pull in build‑time variables like test coverage.
5. Save and test
Click Save. Trigger a manual build that fails (e.g., commit an intentional syntax error). Watch your inbox; if you see the email, you’re good.
If nothing arrives:
- Check Jenkins logs (Manage Jenkins => System Log) for mail errors.
- Verify SMTP credentials again.
- Ensure firewalls aren’t blocking port 587/465.
Common Pitfalls and How to Avoid Them
| Symptom | Likely Cause | Fix |
|---|---|---|
| “SMTP authentication failed” | Wrong password or missing app‑specific token (e.g., Gmail requires an App Password). | Regenerate credentials and update Jenkins. |
| Email never arrives, but logs show “sent successfully”. | Recipient address wrong or mailbox blocked by spam rules. | Verify the email, check spam folder, or whitelist Jenkins’ IP. |
| Emails are huge and hard to read. | Default body includes full console output. | Use the minimal template above or enable Only send on failure in triggers. |
I’ve seen teams waste hours chasing down build failures that never landed in their inboxes because they used the built‑in “Mailer” plugin, which only sends on success unless you tweak it. The Mail Extension plugin is a tiny extra install but saves a ton of headaches.
Wrap‑up
Setting up email notifications in Jenkins isn’t rocket science—just a few clicks and a bit of template tweaking. Once you’re on top of failures (and successes), you’ll spend less time hunting bugs and more time actually building software.
Happy coding, and may your builds stay green!
