Email notification is the feature that lets Jenkins send an email message to people when something happens to a build.

Start with the word build. A build is one run of a Jenkins job: fetch the code, compile it, test it, package it. Each build ends with a result, such as success or failure. Email notification is the messenger that carries that result to human inboxes.

A typical message might say, “The build of the online shop failed. Here is the link to the log. These two people changed the code since the last good build.” The person who receives it can open the link, see what went wrong, and start fixing it, without ever having sat in front of Jenkins.

The main questions email notification answers

• When? After every build, only after failures, only when the status changes, or only when something is fixed.
• Who? A fixed list of people, the developers whose code changed, the person who started the build, or a mix.
• What? A short subject line and a body with the result, a link, a summary of changes, and perhaps the log.
• How? Through a mail server that Jenkins is allowed to use.

Automation only helps if people find out quickly when it needs them.

Picture a team of twenty developers pushing code all day. Jenkins tests every change. One change quietly breaks the login page. If nobody notices for three hours, more changes pile on top, the cause becomes harder to find, and the fix becomes more expensive. If Jenkins emails the responsible developer within minutes, the mistake is still fresh and the repair is often a five-minute job.

Email notification gives four gifts. First, speed: people learn about problems in minutes. Second, focus: the right person hears about it, not everyone. Third, a record: emails are stored in inboxes and can be searched later. Fourth, reach: people who never open Jenkins, such as managers or testers, still stay informed.

A handful of words unlock everything about email in Jenkins. Learn these and the rest feels natural.

Several pieces work together to turn a finished build into an email in someone’s inbox.

A Jenkins system has one controller, the brain, and many agents, the workers. Builds run on agents, but the emails are sent by the controller. The controller holds the mail settings, the stored credentials, and the plugins. When a build finishes, the controller checks the notification rules, builds the message, and hands it to the mail server.

flowchart LR
  AGT["Build Agent"] -->|"build result"| CTRL["Jenkins Controller"]
  CTRL --- MAILPLUG["Mailer and Email Extension Plugins"]
  CTRL --- CRED[("Credentials Store")]
  CTRL --- SETTINGS[("Global Mail Settings")]
  MAILPLUG -->|"compose message"| MSG["Email Message"]
  MSG -->|"SMTP over TLS"| SMTP["SMTP Mail Server"]
  SMTP --> INBOX1["Developer Inbox"]
  SMTP --> INBOX2["Team Mailing List"]
  SMTP --> INBOX3["Manager Inbox"]
  CTRL -->|"link to logs"| UI["Build Page in Jenkins"]
  INBOX1 -->|"click link"| UI

Walking through the picture

The build agent finishes its work and reports the result to the controller. The controller looks at its mail plugins and their rules. If a rule matches, the plugin composes a message using the result, the project name, and the list of changes. The controller fetches the mail server login from the credentials store, connects to the SMTP mail server, and hands the message over. The mail server delivers it to the inboxes of the chosen people. Inside the message is a link back to the build page in Jenkins, so a click takes the reader straight to the log.

The two main plugins

Two plugins do most of the work, and it helps to know the difference.

Before Jenkins can send anything, it must be told which mail server to use. This is a one-time setup for the whole Jenkins system.

Understanding the ports

Logging in to the mail server

Most mail servers ask senders to prove who they are. Jenkins stores the username and password, or better a limited token, in its credentials store, a safe box that keeps secrets encrypted. You choose the credential by name in the mail settings. Many providers today no longer accept a person’s ordinary password for automation. They expect a special app password, an API key, or a modern login method. Ask your mail team which one your provider wants.

The simplest way to get started is the basic post-build action called “E-mail Notification”.

In a classic job, you scroll to the Post-build Actions section and add “E-mail Notification”. You type one or more email addresses, separated by spaces. That is almost all there is to it. There is also a checkbox, “Send separate e-mails to individuals who broke the build”, which lets Jenkins guess the developers whose changes caused trouble and email them too.

What the basic mailer does automatically

• Emails when a build fails. The listed people are told a build broke.
• Emails when a build becomes unstable. Tests failed, but the build itself finished.
• Emails when a broken build is fixed. A “back to normal” message tells everyone the trouble is over.
• Stays quiet while it keeps failing. Jenkins does not repeat the same alarm on every failed build. It mainly speaks when the state changes.

This “speak only on change” behavior is a good default, because it avoids flooding inboxes. The trade-off is that you cannot easily ask for an email after every successful build, or attach the log, or change the wording. For that, you need the extended plugin.

Notification from a pipeline

In a pipeline job, there is a step named mail that sends a basic message. You give it recipients, a subject, and a body. It is normally placed in the post section, so it runs after the stages finish, and it can be tied to a condition, such as “only when the build fails”. The message text is written by you, so it can include the project name and a link.

When the basic mailer feels too small, the Email Extension plugin, often called Email-ext, offers full control.

In a classic job it appears as “Editable Email Notification”. In a pipeline it is available through a step named emailext. Either way, you get four big controls: who receives the message, when it is sent, what it says, and extras such as attachments.

The parts of an extended notification

Triggers: choosing the moment

Recipient providers: choosing the people

The extended plugin can work out recipients from the build itself. These automatic recipient choices are called recipient providers.

Tokens: writing messages that fill themselves in

A token is a placeholder such as the project name, the build number, the build status, or the link to the build page. When Jenkins sends the message, it swaps each token for the real value. This lets you write one message template for many builds. Other tokens can add the list of changes, the last lines of the console log, the test results summary, or the duration. Use them to make messages that answer the reader’s first questions without needing another click.

Let us follow one notification from the moment a build ends to the moment the message reaches an inbox.

sequenceDiagram
  participant B as Build Agent
  participant C as Jenkins Controller
  participant P as Email Plugin
  participant S as SMTP Server
  participant R as Recipient Inbox
  B->>C: Build finished with result
  C->>P: Run post-build email action
  P->>P: Check triggers and choose recipients
  P->>P: Fill tokens and build message
  P->>S: Connect securely and log in
  S-->>P: Accept message
  S->>R: Deliver email
  R-->>R: Reader clicks link to build page

Why the controller sends the mail

Emails are sent by the controller, not by the agent that ran the build. That means the controller must be able to reach the mail server over the network. If your Jenkins runs in a locked-down network, the mail server must be reachable from the controller, and the firewall must allow the chosen port. Agents do not need mail access at all, which is another reason to keep secrets and mail settings on the controller only.

What happens if sending fails

If the mail server is unreachable or rejects the message, the email step usually reports an error in the build log, and depending on settings, the build may still be marked successful, because failing to send a notification is not the same as failing to build. Jenkins does not normally keep a retry queue, so a message lost during a mail server outage is simply lost. This is a reason not to rely on email alone for critical alarms.

Sending an email is easy. Sending one that people read and act on is a craft.

A good subject line

The subject is often all that people read. A great subject says three things at a glance: the result, the project, and the build number. Something like “Failed: online-shop, build 482” tells the reader almost everything before opening the email. Put the status first so that inbox filters and human eyes can scan it quickly.

A good body

Fighting notification fatigue

Notification fatigue happens when people receive so many messages that they stop reading any of them. It is the number one reason email alerts fail in practice. Avoid it with these habits.

• Prefer state changes. Email when a build first breaks and when it is fixed, not on every repeated failure.
• Target the right people. Developers of the changed code should hear first; a manager may only need a daily summary.
• Do not notify on success for busy jobs. A green build every five minutes is not news.
• Use different channels for different urgency. Email for normal news, a chat message or pager for real emergencies.
• Review regularly. If an alert is always ignored, fix its cause or remove it.

Modern Jenkins teams describe their pipeline in a text file called a Jenkinsfile. Email notification fits naturally into it.

A declarative pipeline has a post section that runs after the stages. Inside it you can list conditions such as “always”, “success”, “failure”, “unstable”, “changed”, “fixed”, “regression”, and “aborted”. Each condition can contain an email step. This gives you the same flexibility as extended triggers, but written as text that lives beside your code, where it is versioned and reviewed.

flowchart TD
  ST["Pipeline Stages Finish"] --> POST{"Post Section"}
  POST -->|"failure"| F["Email Developers and Team List"]
  POST -->|"fixed"| X["Email Team: Back to Normal"]
  POST -->|"unstable"| U["Email Testers"]
  POST -->|"always"| CL["Clean Workspace"]
  POST -->|"success"| OK["No email, or Release Notice Only"]

Useful post conditions for email

Emails from inside a stage

Emails do not have to wait until the end. A stage can send a message of its own, for example asking a person to approve a release before the pipeline continues. Such approval emails should always include a clear link to the waiting pipeline and should say what will happen if nobody answers.

Shared libraries for consistent messages

If fifty projects each write their own email text, messages will look different and mistakes will be repeated. Teams often put the notification logic into a shared library, a central collection of reusable pipeline pieces. Every project calls the same “notify” routine, so a wording improvement reaches everyone at once.

Here is the whole story from code change to a reader acting on an email.

flowchart LR
  A["Developer Pushes Code"] --> B["Jenkins Builds and Tests"]
  B --> C{"Result"}
  C -->|"success"| D["Optional Success Notice"]
  C -->|"failure"| E["Failure Email to Developers and Team"]
  E --> F["Developer Opens Build Link"]
  F --> G["Developer Fixes and Pushes"]
  G --> B
  C -->|"fixed after failure"| H["All-Clear Email to Team"]

The link between email and the build page

An email is a doorway, not a warehouse. It should give a short summary and then send the reader to Jenkins for the details. That is why the Jenkins URL setting matters so much. If the URL points to an internal name that readers cannot reach from their phones, the links in the emails will be useless. Check that links work from where people actually read their mail.

Threading and inbox rules

Consistent subject lines let mail programs group messages and let people create filters, such as “put all emails from Jenkins about the payment project into one folder”. Consistency is a quiet but powerful feature. Avoid putting random numbers or changing words into subjects unless they carry real meaning.

Email seems harmless, but the mail connection touches secrets, and messages can leak information.

Protect the mail login

• Use the credentials store. Never type the mail password in a text box that anyone can read.
• Use a dedicated sender account with permission only to send mail, not to read mailboxes.
• Use app passwords or tokens where the provider requires them, and rotate them on a schedule.
• Restrict who can change global mail settings. Only administrators should edit them.

Encrypt the connection

Always use SSL or TLS between Jenkins and the mail server, so nobody on the network can read the login or the message. Avoid plain unencrypted connections, except inside a trusted private network approved by your mail team.

Mind the content

Build logs sometimes contain sensitive details, such as server names, internal paths, or accidentally printed keys. Attaching full logs to emails copies those details into many inboxes. Prefer a link to the log inside Jenkins, where access can be controlled, and limit attachments to what is truly needed.

Be careful with templates and scripts

The extended plugin can run small scripts to decide recipients or tweak the message. Scripts are powerful, so restrict who may write them, and use the plugin’s safety sandbox where available. A careless script can leak data or send mail to unintended people.

Avoid becoming a spam source

If a job sends emails to a huge list, or loops and sends thousands of messages, your mail server may be blocked by the provider. Set sensible limits, avoid triggering emails from builds that run every minute, and make sure only trusted people can edit notification lists.

A message can leave Jenkins perfectly and still never reach the inbox. Understanding why saves hours of confusion.

Receiving mail systems are suspicious by nature, because most email in the world is spam. They check whether a message really comes from the sender it claims. Three common checks are worth knowing, in simple words.

If your “from” address uses your company domain, but Jenkins sends through a server that your domain does not authorize, messages may be sent to spam or rejected outright. The simplest fix is to send through your company’s official mail system or an approved sending service, and to use a “from” address that this system is allowed to send for.

Common delivery symptoms

Watch the notification system itself, because a silent alarm is the most dangerous kind.

Where to look for clues

Every build has a console output, a running diary of everything the build did. When an email step runs, the console shows whether it sent a message and to whom, or whether it hit an error. Jenkins also has a system log that records events from plugins, including mail problems. The mail server keeps its own logs showing which messages it accepted and where it sent them. Together, these three answer the question, “Did the message leave Jenkins, and did it arrive?”

Health checks to run regularly

Many teams also add a small heartbeat: a scheduled job that sends one harmless email to a monitoring address each day. If the heartbeat stops arriving, someone knows the notification path is broken, even when no build has failed.

Email is not the only messenger. Choosing the right channel for the right message makes teams calmer.

A practical mix is to use email for a durable record and for people outside the team, a chat message for quick team awareness, and a pager only for real production emergencies. Jenkins can send to all of these through plugins, sometimes from the same pipeline step.

Every choice has a price. Knowing both sides helps you design notifications wisely.

Choosing between the two plugins

A pattern is a proven habit. An anti-pattern is a tempting shortcut that usually hurts later.

Patterns that work

Anti-patterns to avoid

These habits separate a helpful notification system from an annoying one.

Best practices

1. Set the Jenkins URL correctly so every link in every email works from where people read it.
2. Use a dedicated sender account and store its credential in the credentials store.
3. Encrypt the connection with SSL or TLS, and pick the port that matches your security setting.
4. Test the connection with the built-in test email after every change.
5. Notify on state changes, and add occasional reminders for long-lasting failures.
6. Send failures to the developers who changed the code, with the team on copy.
7. Write clear subjects that start with the result, then the project, then the build number.
8. Keep bodies short, with a link, changes, and a failure summary.
9. Prefer links to attachments, and never include secrets in email content.
10. Keep notification rules in the Jenkinsfile or a shared library, so they are versioned and reviewed.
11. Configure authentication for your domain so receivers trust the messages, meaning SPF, DKIM, and DMARC.
12. Add a heartbeat so a silent failure of the mail path is noticed.
13. Review alerts regularly, and remove or fix any that people always ignore.
14. Use several channels matched to urgency, with email as the durable record.

Common mistakes

Email notification shows up in almost every Jenkins installation. Here are common ways teams use it.

A typical growth story

A small team begins with the basic mailer and a single team address. As the team grows, the emails become noisy, so they switch to the extended plugin and send failures only to the developers who changed the code. Next they move their rules into the Jenkinsfile and then into a shared library, so that every project looks the same. They add a heartbeat after a silent credential expiry costs them a missed failure. Finally they send emergencies to an on-call tool and keep email as the record. At each step the change was small, and the team never had to start over.

You started with a smoke alarm in a kitchen and finished with a full picture of how Jenkins taps people on the shoulder when their builds need attention.