Skip to main content
Email

​
Configure alerts in the Mage Pro UI

You can configure email alerts in the Mage Pro UI instead of editing metadata.yaml directly:
  1. For project defaults, go to Settings > Account > Alerts.
  2. For one pipeline, open the pipeline and go to Alerts. Pipeline-level settings override the project-level alert config for that pipeline.
  3. Choose the alert outcomes, enable Email, and select a delivery method: Custom SMTP or Mage managed email.
  4. Enter recipients or use managed API default recipients when they are configured, then use Send test notification before saving. Custom SMTP sends through your SMTP server; Mage managed email sends through the managed notification service.
You can still reference secrets with values such as {{ env_var('MAGE_SMTP_PASSWORD') }}.

​
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:
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:
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:
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:
In addition to the variables mentioned above (e.g. execution_time, pipeline_uuid, etc), you can also use the following in your message templates in Mage Pro:
  1. start_time
  2. end_time
  3. duration (in seconds)
  4. env (this gets the value stored in the ENV environment variable)
This makes your Email notifications more dynamic and context-aware — ideal for multi-environment deployments and advanced workflows.

​
Managed notification email delivery

Mage Pro can send pipeline status emails through the managed notification delivery API instead of requiring each project to own SMTP credentials. The project or pipeline metadata.yaml owns who receives alerts, while the companion Mage Pro API deployment owns the provider credentials, idempotency, rate limiting, and delivery. Managed email uses the same notification title and body as SMTP email, including the pipeline run link when available. In the Mage UI, enable Email and choose Mage managed email as the delivery method. In metadata.yaml, enable managed email delivery with notification_config.managed_config:
Fields:
  • enabled: opt in to managed delivery.
  • channels: currently supports email only. Include email explicitly when you want managed email delivery.
  • email_config.to_emails: optional direct customer email recipients. Mage trims, deduplicates, and forwards these addresses to the managed API.
  • timeout: total seconds Mage waits for the managed API token exchange and delivery request. Mage caps this value at 30 seconds. Provider-specific request timeouts are configured in the Mage Pro API service.
Mage only forwards email_config when to_emails includes at least one address. Leave to_emails empty to use managed API default recipients when the operator has configured them. Managed notifications are email-only in this implementation. Do not configure sms, sms_config, to_phone_numbers, or phone recipients. Operators configure the companion Mage Pro API with deployment environment variables: For AWS SES SMTP, configure:
  • AWS_SES_FROM_EMAIL: sender address. SES_FROM_EMAIL is also accepted as a fallback.
  • AWS_SES_USERNAME and AWS_SES_PASSWORD: SES SMTP credentials.
  • AWS_SES_REGION, AWS_REGION, or AWS_DEFAULT_REGION: used to build email-smtp.<region>.amazonaws.com when AWS_SES_SMTP_HOST is not set.
  • AWS_SES_SMTP_HOST: optional explicit SMTP host.
  • AWS_SES_SMTP_PORT: SMTP port, default 587.
  • AWS_SES_SMTP_STARTTLS: whether to call STARTTLS, default true.
For Resend, set MANAGED_NOTIFICATION_EMAIL_PROVIDER=resend, RESEND_API_KEY, and RESEND_FROM_EMAIL.

​
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: