**Alert Relay Documentation**

Guidance for building Alert Relay flows, choosing the right action, and understanding SharePoint version-history comparisons.

# Creating Your First Alert Email

This page walks through the fastest path to a working Alert Relay flow that sends an email showing what changed in a SharePoint item.

## What Alert Relay does

Alert Relay is a Power Automate connector for SharePoint change notifications. It helps you move beyond generic "item modified" emails by returning:

- detailed field-level changes
- formatted values ready for display
- ready-to-use HTML for alert emails

## Before you start

You will need:

- a Microsoft 365 account
- access to the SharePoint site, list, or library you want to monitor
- a Power Automate flow that starts from a SharePoint trigger

## Recommended first scenario

For your first test, use:

- SharePoint trigger: `When an item is created or modified`
- Alert Relay action: `Get Detailed Item Alert HTML`
- email action: `Send an email (V2)`

That path gives you the fastest first success.

## Create the connector connection

When you add your first Alert Relay action in Power Automate, create a connection using your Microsoft 365 sign-in

> **Note**  
> A Microsoft 365 administrator may need to approve the connector for your tenant before you can create or use the connection.

## Understand the key inputs

The main Alert Relay actions use these important inputs:

### **Site URL**

Choose the SharePoint site that contains the list or library.

- You can usually pick this from a dropdown.
- You can also enter it manually if needed.

### **List or Library**

Choose the SharePoint list or document library.

- The dropdown refreshes after a site is selected.
- Manual entry can use the exact list title or the list GUID.

### **Item ID**

This is normally the `ID` value from the SharePoint trigger.

### **Compare From**

This tells Alert Relay what point in time or version to compare against.

For most flows, the best option is:

- `TriggerWindowStartToken` from the SharePoint trigger

If you leave `Compare From` blank, Alert Relay uses the first version in the item's version history as the comparison baseline.

## Build your first flow

Use this flow shape:

1. SharePoint trigger: `When an item is created or modified`
2. Alert Relay action: `Get Detailed Item Alert HTML`
3. Outlook action: `Send an email (V2)`

### Step 1: Add the SharePoint trigger

Create an automated cloud flow using:

- `When an item is created or modified`

Choose the correct:

- Site Address
- List Name

### Step 2: Add Get Detailed Item Alert HTML

Add the Alert Relay action:

- `Get Detailed Item Alert HTML`

Populate the fields as follows.

#### **Site URL**

Use the same SharePoint site that the trigger is watching.

#### **List or Library**

Use the same list or library.

#### **Item ID**

Use the trigger's `ID` value.

#### **Compare From**

For the best first result, use:

- `TriggerWindowStartToken`

This allows Alert Relay to compare the current item against the trigger's baseline point.

#### Optional fields

You can also choose to set these fields, which will be reflected in the HTML output:

- **Include Minor Versions** (`includeMinorVersions`): includes draft or minor versions in the comparison instead of using major versions only. Defaults to `false`.
- **Include Unchanged Fields** (`includeUnchangedFields`): includes unchanged fields in the generated output as well as changed fields. Defaults to `true`.
- **Date Format** (`dateFormat`): controls how dates are displayed in the output. Defaults to `yyyy-MM-dd`.
- **Time Format** (`timeFormat`): controls how times are displayed in the output. Defaults to `HH:mm:ss`.
- **Timezone** (`timezone`): controls which timezone Alert Relay uses when displaying date and time values. Defaults to `UTC`.

### Step 3: Add Send an email (V2)

Add your email action after Alert Relay.

Use:

- **Subject**: Alert Relay **Suggested Subject** (`subject`)
- **Body**: Alert Relay **HTML Body** (`htmlBody`)

Make sure the email body is treated as HTML by your chosen mail action.

## Recommended first test item

Use a simple list item that has:

- a Title column
- one or two editable columns such as a Choice column, a Date and Time column, or a Person column

This makes it easier to see how Alert Relay handles both new items and later updates.

## Run the flow

Once you have added the trigger, the Alert Relay action, and your email action, and you have a suitable test item:

1. save/publish the flow
2. make sure the flow is turned on
3. create a new item in the SharePoint list
4. wait for the flow to run
5. open the flow run history
6. confirm the Alert Relay action completed successfully
7. check the email that was sent

After that first run:

1. edit the same item
2. change one or two fields
3. wait for the flow to run again
4. review the second email

This gives you a quick way to test both:

- a newly created item
- an updated item with visible changes

## What to expect

### For a newly created item

The first email is based on a new item, not an update to an existing item.

In that case:

- the suggested subject uses **Item Added** (`subject`) rather than an update-style subject
- the HTML body says the item has been added
- the email shows the item's initial values

### For a modified item

After you edit the same item and the flow runs again, the email should normally include:

- the item title
- who changed it
- when it changed
- the changed fields
- previous and current values, where available
- a link back to the SharePoint item
- a subject using **Item Updated** (`subject`)

## If the dropdowns are empty

Check these first:

- the connector connection is valid
- the signed-in user has access to the SharePoint site
- the selected site URL is correct
- the selected list exists in that site

If needed, you can enter values manually and return to the dropdowns later.

## Common issues

### Using the wrong Item ID

Use the trigger's `ID`, not a different identifier from another action.

### Using the wrong site or list

The Alert Relay action should point to the same SharePoint source the trigger is monitoring.

### Leaving Compare From empty without understanding the result

If you leave `Compare From` blank, Alert Relay compares the current item against the first version in the item's version history. For most trigger-based flows, `TriggerWindowStartToken` is the best starting point.

### The email body is not formatted correctly

Check that your email action is using the Alert Relay HTML output as HTML rather than plain text.