New-AMExecuteAction

New-AMExecuteAction

New-AMExecuteAction

SYNOPSIS

Creates an HTTP action for an Adaptive Card.

SYNTAX

1

New-AMExecuteAction [-Title] <String> [-Verb] <String> [-Url <String>] [-Body <String>] [-Data <Object>] [-Id <String>] [-Verbose <SwitchParameter>] [-Debug <SwitchParameter>] [-ErrorAction <ActionPreference>] [-WarningAction <ActionPreference>] [-InformationAction <ActionPreference>] [-ProgressAction <ActionPreference>] [-ErrorVariable <String>] [-WarningVariable <String>] [-InformationVariable <String>] [-OutVariable <String>] [-OutBuffer <Int32>] [-PipelineVariable <String>] [<CommonParameters>]

DESCRIPTION

Creates an Action.Http element that makes an HTTP request when the action button is clicked. This action is used in Outlook Actionable Messages to trigger server-side operations like approving requests, submitting data, or any other operation requiring a backend API call.

EXAMPLES

EXAMPLE 1

1
2
3
4

# Create a simple approval action
$approveAction = New-AMExecuteAction -Title "Approve" -Verb "POST" `
    -Url "https://api.example.com/approve" `
    -Body '{"requestId": "12345", "status": "approved"}'

EXAMPLE 2

1
2
3
4

# Create an action with dynamic user data
$rejectAction = New-AMExecuteAction -Title "Reject" -Verb "POST" `
    -Url "https://api.contoso.com/api/requests/reject" `
    -Body '{"requestId": "ABC123", "rejectedBy": "", "timestamp": ""}'

EXAMPLE 3

1
2
3
4
5
6
7
8
9

# Create an action with a PowerShell object as data
$data = @{
    requestId = "REQ-789"
    action = "complete"
    comments = "Task completed successfully"
}
$completeAction = New-AMExecuteAction -Title "Mark Complete" -Verb "POST" `
    -Url "https://tasks.example.org/api/complete" `
    -Data $data

PARAMETERS

-Title

The text to display on the action button.

1
2
3
4
5
6
7
8
9

Type: String
Parameter Sets: (All)
Aliases: None

Required: True
Position: 0
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-Verb

The HTTP verb/method to use for the request (e.g., “POST”, “GET”, “PUT”, “DELETE”).

1
2
3
4
5
6
7
8
9

Type: String
Parameter Sets: (All)
Aliases: None

Required: True
Position: 1
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-Url

The URL endpoint that will receive the HTTP request when the button is clicked.

1
2
3
4
5
6
7
8
9

Type: String
Parameter Sets: (All)
Aliases: None

Required: False
Position: 2
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-Body

Optional JSON string containing the payload to send with the request. You can include user-specific tokens like that will be replaced at runtime.

1
2
3
4
5
6
7
8
9

Type: String
Parameter Sets: (All)
Aliases: None

Required: False
Position: 3
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-Data

Optional data object (hashtable) to include with the request. This is an alternative to Body for when you want to specify the data as a PowerShell object rather than a JSON string.

1
2
3
4
5
6
7
8
9

Type: Object
Parameter Sets: (All)
Aliases: None

Required: False
Position: 4
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-Id

Optional unique identifier for the action. If not specified, an empty string is used.

1
2
3
4
5
6
7
8
9

Type: String
Parameter Sets: (All)
Aliases: None

Required: False
Position: 5
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

CommonParameters

This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters.

INPUTS

None. You cannot pipe input to New-AMExecuteAction.

OUTPUTS

System.Collections.Hashtable

Returns a hashtable representing the Action.Http element.

NOTES

In Actionable Messages, the correct action type is “Action.Http”, not “Action.Execute”. Action.Http is used for making HTTP requests when the action is triggered.

For security reasons, the target URL must be registered with the Actionable Email Developer Dashboard and associated with your Originator ID before it can be used in production environments.