Search docs.molo17.com
    Configuration guide Control Plane

    Set up email alerts for platform events

    Core Hub can email you when something needs attention: a pipeline error, an entity that stops, an unhealthy agent. This guide connects Core Hub to an SMTP server, chooses who receives the alerts and which events qualify, and then proves the setup twice: with a test email and with a real alert raised by a failing pipeline.

    In this guide

    You will learn how to open the email settings, enter the SMTP connection details, add alert recipients, filter events and severities, send and read a test email, save the configuration, and trigger a real alert to see it arrive.

    Quick information

    Goal

    Receive Gluesync platform alerts as email digests

    Audience

    Gluesync administrators

    Level

    Basic

    Time required

    About 25 minutes

    Area

    Control Plane → Settings → Notifications → Emails

    Applies to

    Gluesync 2.3

    Before you begin

    Make sure that:

    1. You can sign in to the Gluesync Control Plane with a user that can change platform settings;

    2. You have an SMTP server that Core Hub can reach from its own network, and its host name, port, security mode, and credentials;

    3. You know where the mailbox of the alert recipient is, so that you can read the messages;

    4. A pipeline with a running entity is available for the last steps, and you can change its target in a database tool. Use a test pipeline: the guide makes a target table reject writes on purpose.

    This guide was tested with Mailpit, a local test mailbox: SMTP host mailpit, port 1025, no encryption, and a web inbox at http://localhost:8025. Mailpit accepts any username and password, so the guide uses dummy values. Replace them with the details of your own mail server. The test pipeline is called Alerts demo and replicates a customers entity into the shop_alerts schema of a PostgreSQL target.

    The SMTP host is resolved by Core Hub, not by your browser. When Core Hub runs in a container, use the name or address that is valid inside the container network (here mailpit), not localhost.

    Guide steps

    Open the notification settings

    UI

    1. Sign in to the Gluesync Control Plane;

    2. Select the Settings gear icon in the header;

    3. In the Settings window, select Notifications;

    4. Select the Emails tab;

    5. Select Enable email client.

    The Control Plane header with the Settings gear icon marked by annotation 1
    Figure 1. Open Settings, select Notifications, then the Emails tab.
    The Notifications settings with the Emails tab marked by annotation 1 and the Enable email client checkbox marked by annotation 2
    Figure 2. The Emails tab (1) shows only Enable email client (2) until you turn the email client on.
    Expected result

    The SMTP fields, the recipients list, the filters, and the test controls appear below Enable email client.

    Enter the SMTP connection details

    UI

    Fill in the Configurations section. All fields except the security mode are required.

    1. In SMTP Server, enter the host name or IP address of your mail server;

    2. In Port Number, enter the port of the SMTP service;

    3. In Source connection, choose the encryption that your server expects (see the table below);

    4. In From email, enter the address that appears as the sender of the alert emails;

    5. In Username, enter the SMTP account name;

    6. In Password, enter the SMTP account password. Use the eye icon to show or hide what you type.

    The Configurations section with SMTP Server
    Figure 3. Enter the six connection fields (1 to 6).
    Field What to enter

    SMTP Server

    Host name or IP address of the outgoing mail server, as reachable from Core Hub. Example for this guide: mailpit.

    Port Number

    The SMTP port. Common values are 587 (with TLS), 465 (with SSL), and 25 or a custom port for servers without encryption. Example for this guide: 1025.

    Source connection

    The encryption mode of the connection. TLS upgrades a plain connection with STARTTLS, typically on port 587. SSL opens an encrypted connection from the start, typically on port 465. None sends the mail without encryption. Example for this guide: None.

    From email

    Sender address of every alert and test email. Some providers reject senders that do not belong to the authenticated account.

    Username

    Account used to authenticate with the SMTP server. Gluesync always authenticates, so the field cannot stay empty.

    Password

    Password of that account. The field is masked. After you save, Core Hub keeps the stored password and does not display it again.

    The dropdown that chooses the encryption mode is labeled Source connection in the Control Plane of this release, although it controls the SMTP security mode. This guide uses the label as it appears on screen.
    The encryption dropdown open with the options TLS
    Figure 4. Choose TLS, SSL, or None in the encryption dropdown.
    Expected result

    The six fields contain your values and the encryption dropdown shows the mode that matches your server.

    Add recipients and choose which events qualify

    UI

    1. In Alert recipients, enter the first address in Recipient 1. Core Hub sends the alerts to every address in the list;

    2. To add another recipient, select Add recipient or press Enter. Select the bin icon on a row to remove it. You can add up to 20 addresses; blank rows are skipped when you save;

    3. In Enabled events, open the list and tick the events that should send an email. Select Select all or Clear to change every entry at once;

    4. In Severity filters, tick the severities to receive: Critical, Warning, or Info.

    The Alert recipients list marked by annotation 1
    Figure 5. Add the recipients (1), the events (2), and the severities (3).

    In this guide the filters are:

    Filter Value

    Alert recipients

    ops-team@example.com

    Enabled events

    Agent Unhealthy, Entity CDC Stopped, Entity Snapshot Failed, Pipeline Error (4 of 40)

    Severity filters

    Critical, Warning (2 of 3)

    The Control Plane offers 40 event types, from Agent Recovered to Throughput Anomaly Detected. An email is sent only when the event type and the severity of an event are both selected.

    Expected result

    The Alert recipients header counts your recipients, and the two filter dropdowns show how many items you selected.

    Control batching and scope

    UI

    Scroll down to Burst prevention and Objects filters.

    1. Keep Enable burst prevention selected to collect events into digest emails instead of one email per event;

    2. In Window (minutes), enter how long Core Hub collects events before it sends a digest. This guide uses 1 so that the alert arrives quickly; the default is 5;

    3. In Max events per email, enter the largest digest. When the limit is reached, Core Hub sends the digest immediately. The default is 20;

    4. In Objects filters, select a Pipeline, Group, or Entity to restrict the alerts to those objects. This guide selects the Alerts demo pipeline. With the filters empty, alerts for every object qualify.

    The Burst prevention checkbox marked by annotation 1
    Figure 6. Set the burst window (2, 3) and scope the alerts to one pipeline (4).
    Expected result

    The burst window and the object filters match the alerts you want to receive.

    Alerts are never sent one by one: events wait for the burst window to end (at least one minute), or for Max events per email to be reached, and are then delivered as a single Gluesync alert digest email per recipient. Allow for this delay when you test.
    Send a test email

    UI

    1. Scroll to Test email;

    2. Select Send test email. The button is disabled until at least one recipient is entered.

    The test uses the values currently in the form, so you can check them before you save.

    The Test email section with the Test email sent confirmation marked by annotation 1
    Figure 7. The button changes to Test email sent (1) when the SMTP server accepts the message.
    Expected result

    The button shows Test email sent. If the SMTP server cannot be reached, an Unexpected error notification appears in the upper-right corner of the Control Plane and names the host and port.

    Read the test email in the mailbox

    UI

    1. Open the inbox of the recipient (for Mailpit, http://localhost:8025);

    2. Find the message Gluesync — SMTP test email and open it;

    3. Check the sender, the recipient, and the body, which repeats the server, the security mode, the From address, and the To list.

    The Mailpit inbox with the Gluesync SMTP test email marked by annotation 1
    Figure 8. The test email is listed in the inbox.
    The opened test email with the header fields marked by annotation 1 and the message body marked by annotation 2
    Figure 9. The sender and recipient (1) and the body (2) match the form values.
    Expected result

    The test email arrives within a few seconds and shows the server mailpit:1025, the security NONE, and your sender and recipient addresses.

    Save the configuration

    UI

    1. Scroll to the bottom of the form;

    2. Select Save.

    The Save control showing Saved
    Figure 10. The button changes to Saved (1).
    Expected result

    Saved appears. Core Hub applies the configuration immediately, without a restart, and starts matching events against your filters. If you reload the page and reopen Notifications, the values are still there (the password stays hidden).

    Check that an informational event sends no email

    UI

    The filters in this guide accept Critical and Warning events. Pausing an entity raises Entity CDC Stopped with the severity Info, so it must not send an email.

    1. Open the pipeline that has a running entity;

    2. In the entity row, select the pause icon;

    3. In the Pause customers dialog, select Pause entity;

    4. Wait two minutes, longer than the burst window.

    The entities table of the Alerts demo pipeline with the pause icon of the customers entity marked by annotation 1
    Figure 11. Select the pause icon of the running entity.
    The Pause customers dialog with the Pause entity button marked by annotation 1
    Figure 12. Confirm with Pause entity.
    Expected result

    The entity moves to Hold, and no new message arrives in the inbox. The event type is enabled, but its severity is not.

    Cause a real failure and receive the alert

    UI SQL

    Make the target table of the test pipeline reject new rows, then start the entity so that it tries to write.

    1. In your database tool, connect to the target database of the test pipeline and run:

      ALTER TABLE shop_alerts.customers
  ADD CONSTRAINT alerts_demo_block CHECK (false) NOT VALID;

      NOT VALID leaves existing rows alone and rejects every new or updated row;

    2. In the Control Plane, select the play icon of the paused entity;

    3. In the start dialog, select Full copy, keep Keep and merge, and select Start entity;

    4. Wait until the entity shows the error status;

    5. Open the inbox again and wait for the digest. It arrives about one burst window after the first error.

    The start dialog with the Full copy option marked by annotation 1
    Figure 13. Start the entity with Full copy (1) and Keep and merge (2).
    The entities table with the customers entity in the Error group and its error icon marked by annotation 1
    Figure 14. The entity row shows the error status (1).
    The Gluesync alert digest email in the Mailpit inbox with the subject marked by annotation 1 and the first Pipeline Error card marked by annotation 2
    Figure 15. The digest (1) lists each Pipeline Error with the pipeline, the entity, and the message (2).
    Expected result

    An email titled Gluesync alert digest arrives. Its header badge reads ERROR (the label that the email uses for Critical events), and each card names the pipeline Alerts demo, the entity customers, and the database message that says the row violates the check constraint. A Stack trace section can be expanded in each card.

    The message of a write failure can contain the values of the row that failed. Alert recipients can read that data, so consider who is on the list before you enable Pipeline Error for production pipelines.
    Undo the failure

    SQL

    1. In your database tool, run:

      ALTER TABLE shop_alerts.customers
  DROP CONSTRAINT alerts_demo_block;

    2. In the Control Plane, watch the entity row.

    Expected result

    Core Hub retries the write and the entity returns to the running state without further action, usually within a few seconds.

    Understand how Core Hub applies the filters

    Setting Effect

    Enabled events and Severity filters

    An event must match both lists. In this guide, Entity CDC Stopped is enabled but has the severity Info, so it never produces an email.

    Objects filters

    An event from another pipeline, group, or entity is ignored. Events that do not belong to any pipeline (for example a rejected API request reported as Pipeline Error) are not removed by the Pipeline filter, so such an event can appear in the digest.

    Burst prevention

    Events are collected for Window (minutes) or until Max events per email is reached, and are sent as one digest per recipient. The subject reads Gluesync alert digest (N events).

    Alert recipients

    Each recipient gets a separate message, so one rejected address does not block the others.
    Verify the result

    You have successfully set up email alerts if:

    • Send test email showed Test email sent and the test message is in the inbox;

    • Save showed Saved, and the settings are still present after you reload the page;

    • Pausing the entity (Info) did not send an email;

    • The failing write produced a Gluesync alert digest email that names the pipeline and entity.

    Troubleshooting

    Problem Possible cause What to do

    Send test email is disabled

    The Alert recipients list has no address

    Enter at least one recipient in Recipient 1

    The test email fails and an Unexpected error notification appears

    Core Hub cannot connect to the SMTP server. The Unexpected error notification names the host and port, for example "Couldn’t connect to host, port: mailpit, 2525"

    Check SMTP Server and Port Number from the point of view of Core Hub, then check Source connection against the port

    The test email arrives but no alert follows a real event

    The event type or its severity is not selected, or the object filters exclude the pipeline

    Compare the event and its severity with Enabled events, Severity filters, and Objects filters. Pausing an entity, for example, is an Info event

    The alert arrives a minute or more after the event

    The event waits for the burst window to end

    Lower Window (minutes) or Max events per email, or accept the digest delay

    The digest contains events from other pipelines

    The events do not belong to any pipeline, so the Pipeline filter cannot exclude them

    Narrow Enabled events, or leave the extra events in the digest

    Saved appears but nothing is sent

    Enable email client is cleared, or no recipient is saved

    Select Enable email client, confirm that Alert recipients is not empty, and save again

    Related guides

    Contact MOLO17 Support if you need assistance with email alerts.