Alerting status updates in Email

​

Create notification_config

In the root of your project’s folder (e.g. default_repo/), open the file metadata.yaml.

Project folder name

If you initialized Mage using a different project name, then your root folder will be named differently. default_repo is the default project name if you didn’t customize it.

In the default_repo/metadata.yaml file, add a section with the following configuration or update the existing notification_config section:

notification_config:
  alert_on:
    - trigger_failure
    - trigger_passed_sla

If you omit the alert_on section it will default to trigger_failure and trigger_passed_sla.

Options:

• trigger_failure: alert when a run of a trigger fails
• trigger_success: alert when a run of a trigger succeeds
• trigger_passed_sla: alert when a run of a trigger passes sla

​

Configure email settings

In the default_repo/metadata.yaml file, add a section with the following configuration or update the existing notification_config section:

notification_config:
  alert_on:
    ...
  email_config:
    smtp_host: ...
    smtp_mail_from: ...
    smtp_user: ...
    smtp_password: ...
    to_emails:
      - someone_lucky@mage.ai
      - eng@mage.ai

Change the values for each key under the email_config section.

​

Customize message templates

You can customize message templates in notification_config. Here is an example config:

notification_config:
  alert_on:
    ...
  email_config:
    ...
  message_templates:
    failure:
      title: Failed to execute pipeline {pipeline_uuid} at {execution_time}
      details: >
        Failed to execute pipeline {pipeline_run_url}.
        Pipeline uuid: {pipeline_uuid}. Trigger name: {pipeline_schedule_name}.
        Test custom message.
    success:
      title: ...
      details: ...
    passed_sla:
      title: ...
      details: ...

You can customize the message template for success, failure, passed_sla scenarios. For each message template, you can specify title and either summary or details.

• title is used in email subject
• If you specify the summary, the email body will be your summary + the url of the pipeline run page
• If you specify the details, the details will be used as your email body

To interpolate variables in the message template, you can use {variable_name} syntax. Here are the supported variables:

1. execution_time
2. pipeline_run_url
3. pipeline_schedule_id
4. pipeline_schedule_name
5. pipeline_schedule_description
6. pipeline_uuid
7. error
   • available only for the failure message template
8. stacktrace
   • available only for the failure message template

Note: For pipeline_run_url, the default host is http://localhost:6789. You can specify MAGE_PUBLIC_HOST to be the host url you want to use in the notification messages.

​

🚀 Pro Only: Interpolate Mage Variables in Message Templates

If you’re using Mage Pro, you can interpolate environment variables and other Mage variables directly in your Email message templates using the familiar Jinja-like syntax:

notification_config:
  message_templates:
    failure:
      details: >
        Failed at {{ env_var('ENVIRONMENT') }} environment.
        Pipeline run: {pipeline_run_url}.

This makes your Email notifications more dynamic and context-aware — ideal for multi-environment deployments and advanced workflows.

​

What next?

Whenever a pipeline run is successfully completed or fails, an email will be delivered to all the inboxes listed under to_emails.

Here is an example of what an email could look like: