How to Add Email Notifications to Your GitHub Actions Workflow

Why Email Notifications Matter for CI/CD

When a critical deployment fails at 2 AM, you need to know immediately. While GitHub provides built-in notifications, they can get buried in a noisy inbox. Dedicated email notifications from your workflows give you targeted, actionable alerts for the events that matter most — failed builds, successful deployments, security scan results, and more.

For teams managing many repositories, combine workflow-level emails with platform-level failure analysis and log search so alerts lead to faster root-cause investigation.

In this guide, we'll walk through three popular GitHub Actions for sending email notifications, each with different strengths.

1. dawidd6/action-send-mail — The Most Popular Option

dawidd6/action-send-mail is the most widely used email action on the GitHub Marketplace with over 500 stars. It supports any SMTP server and provides a straightforward configuration.

Basic Setup

name: Send Email on Failure

on:
  workflow_run:
    workflows: ["CI Pipeline"]
    types:
      - completed

jobs:
  notify:
    runs-on: ubuntu-latest
    if: ${{ github.event.workflow_run.conclusion == 'failure' }}
    steps:
      - name: Send failure notification
        uses: dawidd6/action-send-mail@v3
        with:
          server_address: smtp.gmail.com
          server_port: 465
          secure: true
          username: ${{ secrets.EMAIL_USERNAME }}
          password: ${{ secrets.EMAIL_PASSWORD }}
          subject: "❌ CI Pipeline Failed — ${{ github.repository }}"
          to: team@yourcompany.com
          from: GitHub Actions <github-actions@yourcompany.com>
          body: |
            The CI pipeline has failed on branch ${{ github.event.workflow_run.head_branch }}.

            Commit: ${{ github.event.workflow_run.head_sha }}
            Run: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.event.workflow_run.id }}

            Please investigate immediately.

Sending HTML Emails with Attachments

- name: Send test report
  uses: dawidd6/action-send-mail@v3
  with:
    server_address: smtp.gmail.com
    server_port: 465
    secure: true
    username: ${{ secrets.EMAIL_USERNAME }}
    password: ${{ secrets.EMAIL_PASSWORD }}
    subject: "Test Report — ${{ github.repository }}"
    to: team@yourcompany.com
    from: GitHub Actions <github-actions@yourcompany.com>
    html_body: |
      <h2>Test Results</h2>
      <p>Branch: <strong>${{ github.ref_name }}</strong></p>
      <p>Status: <strong style="color: green;">All tests passed</strong></p>
    attachments: test-results/report.html

Key Features

• Supports SMTP and connection string formats
• HTML body and file attachments
• Multiple recipients, CC, and BCC
• Priority levels
• Custom reply-to addresses

2. Action Mailer — Multi-Provider Support with Templates

Action Mailer is a great choice if you want built-in support for popular email providers and HTML templates using Handlebars.

Basic Setup with Gmail

name: Deploy Notification

on:
  push:
    branches: [main]

jobs:
  deploy-and-notify:
    runs-on: ubuntu-latest
    steps:
      - name: Deploy
        run: echo "Deploying..."

      - name: Send deploy notification
        uses: juliansangillo/action-mailer@v1
        with:
          provider: gmail
          username: ${{ secrets.GMAIL_USERNAME }}
          password: ${{ secrets.GMAIL_APP_PASSWORD }}
          to: team@yourcompany.com
          subject: "🚀 Deployed to Production — ${{ github.repository }}"
          body: |
            A new version has been deployed to production.

            Branch: ${{ github.ref_name }}
            Commit: ${{ github.sha }}
            Author: ${{ github.actor }}

Using with SendGrid Provider

- name: Send via SendGrid
  uses: juliansangillo/action-mailer@v1
  with:
    provider: sendgrid
    api-key: ${{ secrets.SENDGRID_API_KEY }}
    to: team@yourcompany.com
    from: noreply@yourcompany.com
    subject: "Weekly Build Summary"
    body: "All builds passed this week."

Key Features

• Built-in provider support (Gmail, Outlook, SendGrid, Mailgun, AWS SES)
• Handlebars HTML templates
• Attachment glob patterns
• Auto-detects provider from configuration

3. SendGrid Action — Direct API Integration

If you're already using SendGrid, the Send Email with SendGrid action provides a direct API integration that's more secure than SMTP — no password needed, just a revocable API key.

Basic Setup

name: Security Scan Notification

on:
  schedule:
    - cron: "0 6 * * 1" # Every Monday at 6 AM

jobs:
  scan-and-notify:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Run security scan
        id: scan
        run: |
          echo "Running security scan..."
          echo "vulnerabilities=0" >> $GITHUB_OUTPUT

      - name: Send scan results
        uses: mmichailidis/sendgrid-mail-action@v1
        with:
          sendgrid-api-key: ${{ secrets.SENDGRID_API_KEY }}
          to: security@yourcompany.com
          from: github-actions@yourcompany.com
          subject: "🔒 Weekly Security Scan — ${{ github.repository }}"
          content: |
            Security scan completed for ${{ github.repository }}.

            Vulnerabilities found: ${{ steps.scan.outputs.vulnerabilities }}
            Full report: ${{ github.server_url }}/${{ github.repository }}/security

Key Features

• Uses SendGrid API (no SMTP configuration needed)
• API keys are revocable and more secure than passwords
• Simple, focused interface
• Ideal if you already have a SendGrid account

Security Best Practices

When configuring email notifications in your workflows, keep these security practices in mind:

1. Always Use GitHub Secrets

Never hardcode credentials in your workflow files. Store all sensitive values as GitHub Secrets:

# ✅ Correct — using secrets
username: ${{ secrets.EMAIL_USERNAME }}
password: ${{ secrets.EMAIL_PASSWORD }}

# ❌ Wrong — never do this
username: "my-email@gmail.com"
password: "my-password-123"

2. Prefer API Keys Over Passwords

API keys are:

• Revocable — you can disable them without changing your email password
• Scoped — they can be limited to only send emails
• Auditable — usage can be tracked separately

Use SendGrid, Mailgun, or similar services that offer API key authentication.

3. Pin Action Versions

Always pin to a specific major version or commit SHA to prevent supply chain attacks:

# ✅ Good — pinned to major version
uses: dawidd6/action-send-mail@v3

# ✅ Better — pinned to commit SHA
uses: dawidd6/action-send-mail@2ba21f34c9b03d6f23922b792bc4e8379ddfb4d2

# ❌ Risky — using latest
uses: dawidd6/action-send-mail@master

4. Use Gmail App Passwords

If using Gmail SMTP, create an App Password instead of your account password. This requires 2-factor authentication to be enabled.

Which Action Should You Choose?

For most teams, dawidd6/action-send-mail is the safest choice — it's the most popular, actively maintained, and works with any SMTP server. If you're already using SendGrid, the dedicated SendGrid action is simpler and more secure.

A Simpler Approach: Built-in Notifications with Gitera

All the actions above require you to add a dedicated step to every workflow YAML file where you want notifications. That means more configuration to maintain, more secrets to manage, and more places where things can break.

What if you didn't have to touch your workflow files at all?

Gitera's Alerting System provides built-in email and Slack notifications for your GitHub Actions workflows — with zero changes to your YAML files. Here's how it's different:

• No workflow modifications required — Gitera monitors your workflows externally and sends notifications based on rules you define in a simple UI, not in YAML
• Multi-channel out of the box — Get notified via email and Slack from the same rule, without configuring separate actions
• Custom alert rules — Create rules based on workflow status (success, failure), specific repositories, or specific workflows — all through a visual dashboard
• No secrets management — Since notifications are handled by Gitera's platform, you don't need to store SMTP credentials or API keys in your repository secrets
• Alert history and analytics — Track notification patterns over time, identify recurring failures, and reduce alert noise

Instead of adding this to every workflow:

# ❌ You have to add this step to EVERY workflow
- name: Send notification
  if: failure()
  uses: dawidd6/action-send-mail@v3
  with:
    server_address: smtp.gmail.com
    server_port: 465
    username: ${{ secrets.EMAIL_USERNAME }}
    password: ${{ secrets.EMAIL_PASSWORD }}
    subject: "Workflow Failed"
    to: team@yourcompany.com
    from: github-actions@yourcompany.com
    body: "Check the logs..."

You simply create a notification rule once in Gitera's dashboard, and it applies to all your workflows automatically.

Get started with Gitera's Alerting System →

Wrapping Up

Adding email notifications to your GitHub Actions workflows can be done in two ways:

1. Third-party actions (dawidd6/action-send-mail, Action Mailer, SendGrid) — great for simple, per-workflow notifications where you need full control over the email content and timing
2. Gitera's built-in alerting — ideal when you want notifications across all your workflows without modifying any YAML files, plus alert history and multi-channel support out of the box

If you're managing a handful of workflows, a third-party action might be all you need. But as your organization scales and you're managing dozens or hundreds of workflows, maintaining notification steps in every YAML file becomes a burden. That's where a platform-level solution like Gitera shines.

See also: workflow management for cross-repo pipeline visibility and our GitHub Actions observability guide for a full platform checklist.