Skip to main content
The Email Extension (Email‑ext) plugin for Jenkins replaces the built-in email notifier and gives you fine-grained control over:
  • when emails are sent (triggers),
  • who receives them (recipient options and tokens), and
  • the exact email content (HTML, templates, attachments, and scripts).
This guide shows how to install the plugin, configure system-wide defaults (SMTP, content type, recipients, templates), and set up job-level notifications for Freestyle jobs — including how to attach build logs and troubleshoot empty-recipient errors. Install the plugin and restart Jenkins after installation. The plugin documentation includes additional examples and configuration notes.
Screenshot of the Jenkins "Email Extension" plugin page in a dark theme, showing documentation links and feature sections on the left and version/installation stats and links on the right. The top has Jenkins navigation and tabs for Documentation, Releases, Issues, Dependencies, and Health Score.

​
System-wide configuration

  1. Open Manage Jenkins → Configure System and search for “Extensible” to find the Editable Email Notification section.
  2. Configure SMTP and authentication:
    • SMTP server: smtp.gmail.com
    • Port: 465 (SSL) or 587 (TLS)
    • Add credentials (username/password or App Password) via Jenkins Credentials, then click Advanced to choose SSL/TLS and other options.
Callouts and security notes:
If you use Gmail, enable 2‑step verification and create an App Password for Jenkins. Do not use your normal account password.
Below is a quick reference for common SMTP settings:

​
Default content type and recipients

You can set global defaults that jobs inherit:
  • Default Content Type: Plain Text or HTML
  • Default Recipients: comma-separated emails (available as the token \$DEFAULT_RECIPIENTS)
  • Default Reply‑To, Default Subject, Default Body.
Set Default Content Type to HTML if you want richer email formatting.
A dark-themed browser window showing the Jenkins "Manage Jenkins > System" configuration page, specifically the email settings with the "Default Content Type" dropdown open (Plain Text selected) and fields for default user e-mail suffix and recipients. Save and Apply buttons are visible at the bottom.
Some additional fields and examples:
  • List-ID examples (keep values in code if they contain angle brackets):
  • Default recipients: a comma-separated list of email addresses. When present, jobs can reference them using \$DEFAULT_RECIPIENTS and \$DEFAULT_REPLYTO.
Use this simple shell snippet to intentionally fail a job for testing email triggers:

​
Default subject and body templates

Email‑ext supports tokens/variables. Common system defaults: Default subject:
Default body:

​
Attachments and limits

You can attach files (for example, the build log). The attachment size limit can be left blank or set to -1 to indicate no limit. Options include compressing the log or attaching the raw build.log.

​
Triggers and default behavior

Email‑ext ships with multiple triggers (e.g., “Failure - Any”). Important behavior to know:
  • Some triggers (like “Send to Developers” or “Send to Culprits”) only include those groups and do not automatically include \$DEFAULT_RECIPIENTS unless the trigger is explicitly configured to do so.
  • If a trigger is evaluated but no recipients are selected, the plugin will skip sending.
A dark-themed screenshot of the Jenkins "Manage Jenkins > System" configuration page showing a list of notification trigger checkboxes (e.g., Failure - Any is checked). The bottom shows "Content Token Reference" and Save/Apply buttons.

​
Job-level configuration (Freestyle job)

  1. Open the job (e.g., npm-version-test) → Configure.
  2. In Post‑build Actions, remove any older/in-built Email‑ext entry if present, then add Editable Email Notification.
  3. For the project recipient list you can:
    • Add explicit comma-separated email addresses, or
    • Leave blank and rely on \$DEFAULT_RECIPIENTS (if your trigger includes it), or
    • Configure recipients per-trigger (recommended when using group options like Developers/Culprits).
If the job runs the failing shell snippet above and you see this log message:
it means a trigger evaluated to send email but no recipients were actually selected for that trigger (either project recipients are empty and the trigger is set to send only to Developers/Culprits, or defaults were not picked up by that trigger).
A dark-themed Jenkins "Manage Jenkins → System" configuration page showing Email Extension settings, with the "Default Recipients" field highlighted and containing an email address. Save and Apply buttons are visible at the bottom.
If you leave the project recipient list empty and use a trigger that only targets Developers/Culprits, email will not be sent to your \$DEFAULT_RECIPIENTS unless you explicitly include that token in the trigger or project recipients.

​
Fix: add recipients for the trigger

In the job’s post-build action for a specific trigger (for example, Failure - Any), add one of the following:
  • explicit email addresses (comma-separated),
  • the token \$DEFAULT_RECIPIENTS,
  • or select one of the provided recipient options (Send To Developers, Send To Culprits, Build User, etc.).
A dark-themed Jenkins job configuration screen showing the "Post-build Actions" section with an open dropdown of email recipient options (e.g., Build User, Culprits, Developers) from the Email Extension plugin. The page includes Save/Apply buttons and a left navigation with sections like General and Build Triggers.
After adding recipients and re-running the job, the console should show the plugin sending the email, for example:

​
Email content, templates, and attachments

  • The job uses the system default subject/body unless you override them at the project level.
  • You can provide HTML bodies or custom templates per job.
  • Attach the build log via the plugin UI or use presend/postsendscripts:
  • Optionally compress logs before attaching.
The sent message will include the configured subject/body and attachments (for example, build.log) when enabled.
An open Gmail message with the subject "npm-version-test - Build #14 - Still Failing!" showing a build.log attachment. The email body includes a link to a Jenkins job (localhost).

​
Tokens and common variables

​
Summary / Checklist

  • Install Email Extension plugin and restart Jenkins.
  • Configure SMTP and credentials (Gmail users: create an App Password).
  • Set system defaults: content type (HTML vs Plain), \$DEFAULT_RECIPIENTS, subject, body, and attachment limits.
  • For each job, add an Editable Email Notification in Post-build Actions.
  • Ensure the triggers include recipients explicitly (project list, \$DEFAULT_RECIPIENTS, or recipient groups such as Developers/Culprits).
  • Enable attachments, use presend/postsend scripting if needed, and customize HTML/template content as required.
Further reading and references: That’s all for this guide — advanced templating and scripting examples are outside this article’s scope.

Watch Video