> ## Documentation Index
> Fetch the complete documentation index at: https://notes.kodekloud.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Demo Email Extension Notification Freestyle
> Guide to installing and configuring Jenkins Email Extension plugin for Freestyle jobs including SMTP setup, templates, triggers, recipients, attachments, and troubleshooting.
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.
## 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:
| Provider | SMTP server | SSL/TLS port | Notes |
| - | -: | -: | - |
| Gmail | `smtp.gmail.com` | `465` (SSL) or `587` (TLS) | Use an `App Password` (requires 2‑step verification) |
| Generic SMTP | `` | `25`, `465`, or `587` | Consult your mail provider for exact 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.
Some additional fields and examples:
* List-ID examples (keep values in code if they contain angle brackets):
```text theme={null}
Build Notifications
"Build Notifications"
```
* 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:
```bash theme={null}
echo "Updating job config using Jenkins CLI"
node -v
npm -v
exit 1
```
## Default subject and body templates
Email‑ext supports tokens/variables. Common system defaults:
Default subject:
```text theme={null}
$PROJECT_NAME - Build # $BUILD_NUMBER - $BUILD_STATUS!
```
Default body:
```text theme={null}
$PROJECT_NAME - Build # $BUILD_NUMBER - $BUILD_STATUS:
Check console output at $BUILD_URL to view the results.
```
## 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.
## 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:
```text theme={null}
An attempt to send an e-mail to empty list of recipients, ignored.
```
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).
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.).
After adding recipients and re-running the job, the console should show the plugin sending the email, for example:
```text theme={null}
Email was triggered for: Failure - Any
Sending email for trigger: Failure - Any
Sending email to: sid.live.demos@gmail.com
```
## 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:
```text theme={null}
$DEFAULT_PRESEND_SCRIPT
$DEFAULT_POSTSEND_SCRIPT
```
* Optionally compress logs before attaching.
The sent message will include the configured subject/body and attachments (for example, `build.log`) when enabled.
## Tokens and common variables
| Token | Meaning |
| - | - |
| `\$PROJECT_NAME` | Jenkins project/job name |
| `\$BUILD_NUMBER` | Build number |
| `\$BUILD_STATUS` | Build result (SUCCESS/FAILURE/etc.) |
| `\$BUILD_URL` | URL to the build console |
| `\$DEFAULT_RECIPIENTS` | System default recipients configured in Manage Jenkins |
| `\$DEFAULT_REPLYTO` | System default reply-to address |
## 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:
* Email Extension plugin: [https://plugins.jenkins.io/email-ext](https://plugins.jenkins.io/email-ext)
* Gmail App Passwords: [https://support.google.com/accounts/answer/185833?hl=en](https://support.google.com/accounts/answer/185833?hl=en)
That's all for this guide — advanced templating and scripting examples are outside this article's scope.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.