The GraphAppToolkit module provides a set of functions and classes to quickly create, configure, and manage Azure AD (Entra) application registrations for various Microsoft 365 scenarios. It focuses on app-only authentication with certificates, storing credentials securely in SecretManagement vaults, and simplifying tasks like sending emails from a service principal, managing mail-enabled groups, and publishing specialized apps for M365 auditing or MEM policy management.
- ExchangeOnlineManagement
- Microsoft.Graph
- Microsoft.PowerShell.SecretManagement
- SecretManagement.JustinGrote.CredMan
- One Exchange Plan 1 license needed.
- Optional: Workload Identities Premium License ($3.60ish per workload) for location restrictions.
- One Mail Enabled Security Group.
- One Email App policy configured to restrict the app to send mail on behalf of users in the Mail Enabled Security Group only.
- One or more self-signed certificates for the app installed locally in the machine store for automated runs.
- Permission used for app registration: Mail.Send (Application)/Send mail as any user. The process guides you to grant admin consent.
- MgGraph Permission for app creation: Application.ReadWrite.All, DelegatedPermissionGrant.ReadWrite.All, and Directory.ReadWrite.All.
- Application.ReadWrite.All
- DelegatedPermissionGrant.ReadWrite.All
- Directory.ReadWrite.All
- Application.ReadWrite.All
- DelegatedPermissionGrant.ReadWrite.All
- Directory.ReadWrite.All
- RoleManagement.ReadWrite.Directory
- Mail.Send
- AppCatalog.ReadWrite.All
- Channel.Delete.All
- ChannelMember.ReadWrite.All
- ChannelSettings.ReadWrite.All
- Directory.Read.All
- Group.ReadWrite.All
- Organization.Read.All
- Policy.Read.All
- Domain.Read.All
- TeamSettings.ReadWrite.All
- User.Read.All
- Sites.Read.All
- Sites.FullControl.All
- Exchange.ManageAsApp
- If ReadOnly is set to $true:
- DeviceManagementConfiguration.Read.All
- DeviceManagementApps.Read.All
- DeviceManagementManagedDevices.Read.All
- Policy.Read.ConditionalAccess
- Policy.Read.All
- If ReadWrite is set to $true:
- DeviceManagementConfiguration.ReadWrite.All
- DeviceManagementApps.ReadWrite.All
- DeviceManagementManagedDevices.ReadWrite.All
- Policy.ReadWrite.ConditionalAccess
- Policy.Read.All
In addition to in-line PowerShell help (Get-Help <FunctionName> -Full), you can refer to the about_GraphAppToolkit.help.txt file (if included in the module) or any published documentation for more details on usage.
The following Public Functions are exposed by the GraphAppToolkit module:
-
New-MailEnabledSendingGroup Creates a new mail-enabled security group in Exchange Online for restricted send scenarios.
-
Publish-TkEmailApp Publishes a Microsoft Graph Email App with certificate-based authentication and optionally restricts sending to a specific mail-enabled group.
-
Publish-TkM365AuditApp Publishes an Azure AD application with read-only or read-write sets of Graph/SharePoint/Exchange permissions for auditing or compliance tasks.
-
Publish-TkMemPolicyManagerApp Publishes an Azure AD application for MEM (Intune) policy management, supporting read-only or read-write permissions.
-
Send-TkEmailAppMessage Sends an email using a previously published email app’s certificate-based authentication (no user mailbox required).
The following Private Functions support the module’s internal processes and are not exported:
- Connect-TkMsService
- ConvertTo-ParameterSplat
- Initialize-TkAppAuthCertificate
- New-TkAppSpOauth2Registration
- Initialize-TkModuleEnv
- Initialize-TkAppName
- New-TkAppRegistration
- New-TkExchangeEmailAppPolicy
- Initialize-TkRequiredResourcePermissionObject
- Set-TkJsonSecret
- Test-IsAdmin
- Write-AuditLog
These private functions handle core logic like certificate generation, connecting to Microsoft services, app registration, secret storage, and logging.
$DefaultDomain = 'contoso.com'
$MailEnabledSendingGroupToCreate = "CTSO-GraphAPIMail"
# Creates a mail-enabled security group named "CTSO-GraphAPIMail" using a default domain
$group = New-MailEnabledSendingGroup -Name $MailEnabledSendingGroupToCreate -DefaultDomain $DefaultDomain# Each Scenario assumes you have a mail-enabled group created in Exchange Online in the $group variable or manually
# set the MailEnabledSendingGroup parameter to a valid email address.
# Scenario 1: Create a new Graph Email App with a certificate for one tenant.
$LicensedUserToSendAs = '[email protected]'
$TwoToFourLetterCompanyAbbreviation = "CTSO"
Publish-TkEmailApp `
-AppPrefix $TwoToFourLetterCompanyAbbreviation `
-AuthorizedSenderUserName $LicensedUserToSendAs `
-MailEnabledSendingGroup $group.PrimarySmtpAddress `
-ReturnParamSplat
# Scenario 2: Attach a certificate to an existing Graph Email App for another tenant.
# Prepare the first tenant and use the default App Prefix 'Gtk' and create an alternate cert prefix
$LicensedUserToSendAs = '[email protected]'
$CertPrefix = "CTSO"
Publish-TkEmailApp `
-CertPrefix $CertPrefix `
-AuthorizedSenderUserName $LicensedUserToSendAs `
-MailEnabledSendingGroup $group.PrimarySmtpAddress `
-ReturnParamSplat
# The initial app will be created with the name 'GraphToolKit-Gtk-<Session AD Domain>-As-helpdesk'
# The certificate prefix will be 'CTSO' and the app will be updated with the new certificate
# Param Splat will have all values populated
$params = @{
AppId = 'your-app-id'
Id = 'your-app-object-id'
AppName = 'GraphToolKit-Gtk-<Session AD Domain>-As-helpdesk'
CertificateSubject = 'GraphToolKit-CTSO-<Session AD Domain>-As-helpdesk'
AppRestrictedSendGroup = '[email protected]'
CertExpires = 'yyyy-MM-dd HH:mm:ss'
CertThumbprint = 'your-cert-thumbprint'
ConsentUrl = 'https://login.microsoftonline.com/<your-tenant-id>/adminconsent?client_id=<your-app-id>'
DefaultDomain = 'contoso.com'
SendAsUser = 'helpdesk'
SendAsUserEmail = '[email protected]'
TenantID = 'your-tenant-id'
}
# Add the new certificate to the existing app
$useExistingParams = @{
ExistingAppObjectId = $params.Id
CertPrefix = 'NewCompany'
OverwriteVaultSecret = $true # optional, if you want to overwrite the existing vault secret
ReturnParamSplat = $true # optional, returns the param splat
}
Publish-TkEmailApp @useExistingParams
# Example app internal notes that will populate in the tenant ui after adding two certificates.
# Assists in tracking the app's usage and configuration.
<#
{
"GraphEmailAppFor": "[email protected]",
"RestrictedToGroup": "[email protected]",
"AppPermissions": "Mail.Send",
"New-Company_ClientIP": "<Public IP Address of the client where the app was called>",
"New-Company_Host": "<Host of the client where the app was called>",
"NewCoolCompany_ClientIP": "<Public IP Address of the client where the app was called>",
"NewCoolCompany_Host": "Host of the client where the app was called>"
}
#># Param Splat returned from Example 2 will have all values populated
# Note subsequent additions to certificates will output a new param splat without the consent URL
$params = @{
AppId = 'your-app-id'
Id = 'your-app-object-id'
AppName = 'GraphToolKit-Gtk-<Session AD Domain>-As-helpdesk'
CertificateSubject = 'GraphToolKit-CTSO-<Session AD Domain>-As-helpdesk'
AppRestrictedSendGroup = '[email protected]'
CertExpires = 'yyyy-MM-dd HH:mm:ss'
CertThumbprint = 'your-cert-thumbprint'
ConsentUrl = 'https://login.microsoftonline.com/<your-tenant-id>/adminconsent?client_id=<your-app-id>'
DefaultDomain = 'contoso.com'
SendAsUser = 'helpdesk'
SendAsUserEmail = '[email protected]'
TenantID = 'your-tenant-id'
}
# Sends an email using a previously published TkEmailApp
Send-TkEmailAppMessage `
-AppName $params.AppName `
-To '[email protected]' `
-FromAddress $params.SendAsUserEmail `
-Subject 'Test Email' `
-EmailBody 'This is a test email.' `
-AttachmentPath 'C:\temp\attachmentFile.zip', 'C:\temp\anotherAttachmentFile.zip' `
-ReturnParamSplat
# Send using manual parameters
$AppId = "00000000-1111-2222-3333-444444444444"
$TenantId = "00000000-1111-2222-3333-444444444444"
$CertThumbprint = "AABBCCDDEEFF11223344556677889900"
$To = "[email protected]"
$FromAddress = '[email protected]'
Send-TkEmailAppMessage `
-AppId $AppId `
-TenantId $TenantId `
-CertThumbprint $CertThumbprint `
-To $To `
-FromAddress $FromAddress `
-Subject "Manual Email" `
-EmailBody "Hello from Manual!"# Publishes a M365 audit app (e.g., for directory or device management auditing)
Publish-TkM365AuditApp -AppPrefix "CSN" -CertThumbprint "FACEBEEFBEEFAABBCCDDEEFF11223344"# Publishes a read-write MEM Policy Manager app with a self-signed cert
Publish-TkMemPolicyManagerApp -AppPrefix "MEM" -ReadWriteCreates or retrieves a mail-enabled security group with a custom or default domain.
New-MailEnabledSendingGroup -Name <String> [-Alias <String>] -PrimarySmtpAddress <String> [-LogOutputPath <String>] [-WhatIf] [-Confirm] [<CommonParameters>]
New-MailEnabledSendingGroup -Name <String> [-Alias <String>] -DefaultDomain <String> [-LogOutputPath <String>] [-WhatIf] [-Confirm] [<CommonParameters>]
| Name | Alias | Description | Required? | Pipeline Input | Default Value |
|---|---|---|---|---|---|
| Name | The name of the mail-enabled security group to create or retrieve. This is also used as the alias if no separate Alias parameter is provided. | true | false | ||
| Alias | An optional alias for the group. If omitted, the group name is used as the alias. | false | false | ||
| PrimarySmtpAddress | \(CustomDomain parameter set) The full SMTP address for the group \(e.g. "[email protected]"). This parameter is mandatory when using the 'CustomDomain' parameter set. | true | false | ||
| DefaultDomain | \(DefaultDomain parameter set) The domain portion to be appended to the group alias \(e.g. "Alias@DefaultDomain"). This parameter is mandatory when using the 'DefaultDomain' parameter set. | true | false | ||
| LogOutputPath | An optional path to output the log file. If not provided, logs will not be written to a file. | false | false | ||
| WhatIf | wi | false | false | ||
| Confirm | cf | false | false |
- None. This function does not accept pipeline input.
- Microsoft.Exchange.Data.Directory.Management.DistributionGroup Returns the newly created or existing mail-enabled security group object.
- Requires connectivity to Exchange Online \(Connect-TkMsService -ExchangeOnline). - The caller must have sufficient privileges to create or modify distribution groups. - DefaultParameterSetName = 'CustomDomain'.
EXAMPLE 1
New-MailEnabledSendingGroup -Name "SecureSenders" -DefaultDomain "contoso.com"
Creates a new mail-enabled security group named "SecureSenders" with a primary SMTP address
of SecureSenders@contoso.com.EXAMPLE 2
New-MailEnabledSendingGroup -Name "SecureSenders" -Alias "Senders" -PrimarySmtpAddress "[email protected]"
Creates a new mail-enabled security group named "SecureSenders" with an alias "Senders"
and a primary SMTP address of Senders@customdomain.org.Publishes a new or existing Graph Email App with specified configurations.
Publish-TkEmailApp [-AppPrefix <String>] -AuthorizedSenderUserName <String> -MailEnabledSendingGroup <String> [-CertPrefix <String>] [-CertThumbprint <String>] [-KeyExportPolicy <String>] [-VaultName <String>] [-OverwriteVaultSecret] [-ReturnParamSplat] [-DoNotUseDomainSuffix] [-LogOutput <String>] [-WhatIf] [-Confirm] [<CommonParameters>]
Publish-TkEmailApp -ExistingAppObjectId <String> -CertPrefix <String> [-CertThumbprint <String>] [-KeyExportPolicy <String>] [-VaultName <String>] [-OverwriteVaultSecret] [-ReturnParamSplat] [-DoNotUseDomainSuffix] [-LogOutput <String>] [-WhatIf] [-Confirm] [<CommonParameters>]
| Name | Alias | Description | Required? | Pipeline Input | Default Value |
|---|---|---|---|---|---|
| AppPrefix | The prefix used to initialize the Graph Email App. Must be 2-4 characters, letters, and numbers only. Default is 'Gtk'. | false | false | Gtk | |
| AuthorizedSenderUserName | The username of the authorized sender. Must be a valid email address. | true | false | ||
| MailEnabledSendingGroup | The mail-enabled security group. Must be a valid email address. | true | false | ||
| ExistingAppObjectId | The AppId of the existing App Registration to which you want to attach a certificate. Must be a valid GUID. | true | false | ||
| CertPrefix | Prefix to add to the certificate subject for the existing app. | false | false | ||
| CertThumbprint | The thumbprint of the certificate to be retrieved. Must be a valid 40-character hexadecimal string. | false | false | ||
| KeyExportPolicy | Key export policy for the certificate. Valid values are 'Exportable' and 'NonExportable'. Default is 'NonExportable'. | false | false | NonExportable | |
| VaultName | If specified, use a custom vault name. Otherwise, use the default 'GraphEmailAppLocalStore'. | false | false | GraphEmailAppLocalStore | |
| OverwriteVaultSecret | If specified, overwrite the vault secret if it already exists. | false | false | False | |
| ReturnParamSplat | If specified, return the parameter splat for use in other functions. | false | false | False | |
| DoNotUseDomainSuffix | Switch to add session domain suffix to the app name. | false | false | False | |
| LogOutput | If specified, log the output to the console. | false | false | ||
| WhatIf | wi | false | false | ||
| Confirm | cf | false | false |
This cmdlet requires that the user running the cmdlet have the necessary permissions to create the app and connect to Exchange Online.
EXAMPLE 1
# Permissions required for app registration:
- 'Application.ReadWrite.All'
- 'DelegatedPermissionGrant.ReadWrite.All'
- 'Directory.ReadWrite.All'
- 'RoleManagement.ReadWrite.Directory'
# Permissions granted to the app:
- 'Mail.Send' (Application) - Send mail as any user
# Exchange application policy restricts send to a mail enabled security group
# Ensure a mail enabled sending group is created first:
$DefaultDomain = 'contoso.com'
$MailEnabledSendingGroupToCreate = "CTSO-GraphAPIMail"
# Creates a mail-enabled security group named "MySenders" using a default domain
$group = New-MailEnabledSendingGroup -Name $MailEnabledSendingGroupToCreate -DefaultDomain $DefaultDomain
# Create a new Graph Email App for a single tenant
$LicensedUserToSendAs = '[email protected]'
Publish-TkEmailApp `
-AuthorizedSenderUserName $LicensedUserToSendAs `
-MailEnabledSendingGroup $group.PrimarySmtpAddress `
-ReturnParamSplat
# Returns an app named like 'GraphToolKit-Gtk-<Session AD Domain>-As-helpdesk'
# Returns a param splat that can be used as input for the send mail function:
# Example:
$params = @{
AppId = 'your-app-id'
Id = 'your-app-object-id'
AppName = 'GraphToolKit-Gtk-<Session AD Domain>-As-helpdesk'
CertificateSubject = 'GraphToolKit-GTK-<Session AD Domain>-As-helpdesk'
AppRestrictedSendGroup = '[email protected]'
CertExpires = 'yyyy-MM-dd HH:mm:ss'
CertThumbprint = 'your-cert-thumbprint'
ConsentUrl = 'https://login.microsoftonline.com/<your-tenant-id>/adminconsent?client_id=<your-app-id>'
DefaultDomain = 'contoso.com'
SendAsUser = 'helpdesk'
SendAsUserEmail = '[email protected]'
TenantID = 'your-tenant-id'
}EXAMPLE 2
# Create a multi client app registration where one app exists and multiple certificates are associated to the app:
# Initial setup:
# Create the group as before (or reuse the existing group) and run the following commands:
$LicensedUserToSendAs = '[email protected]'
$CertPrefix = "CTSO" # First Company prefix. This will be used to prefix the certificate subject.
Publish-TkEmailApp `
-CertPrefix $CertPrefix `
-AuthorizedSenderUserName $LicensedUserToSendAs `
-MailEnabledSendingGroup $group.PrimarySmtpAddress `
-ReturnParamSplat
# Returns an app named like 'GraphToolKit-Gtk-<Session AD Domain>-As-helpdesk'
$params = @{
AppId = 'your-app-id'
Id = 'your-app-object-id'
AppName = 'GraphToolKit-Gtk-<Session AD Domain>-As-helpdesk'
CertificateSubject = 'GraphToolKit-CTSO-<Session AD Domain>-As-helpdesk'
AppRestrictedSendGroup = '[email protected]'
CertExpires = 'yyyy-MM-dd HH:mm:ss'
CertThumbprint = 'your-cert-thumbprint'
ConsentUrl = 'https://login.microsoftonline.com/<your-tenant-id>/adminconsent?client_id=<your-app-id>'
DefaultDomain = 'contoso.com'
SendAsUser = 'helpdesk'
SendAsUserEmail = '[email protected]'
TenantID = 'your-tenant-id'
}
$useExistingParams = @{
ExistingAppObjectId = $params.Id
CertPrefix = 'NewCompany'
OverwriteVaultSecret = $true # optional, if you want to overwrite the existing vault secret
ReturnParamSplat = $true # optional, returns the param splat
}
Publish-TkEmailApp @useExistingParams
# The new Cert will be prefixed with the new company prefix and will allow the current client to authenticate.
# Back in the app registrations console, if you look at the internal notes in the properties of the app:
# The app's "Internal Notes" will be populated with the following json:
# Assists in tracking the app's usage and configuration.
{
"GraphEmailAppFor": "[email protected]",
"RestrictedToGroup": "[email protected]",
"AppPermissions": "Mail.Send",
"New-Company_ClientIP": "<Public IP Address of the client where the app was called>",
"New-Company_Host": "<Host of the client where the app was called>",
"NewCoolCompany_ClientIP": "<Public IP Address of the client where the app was called>",
"NewCoolCompany_Host": "Host of the client where the app was called>"
}
# New cert additions added through the toolkit will append new client info to these notes.Publishes \(creates) a new M365 Audit App registration in Entra ID \(Azure AD) with a specified certificate.
Publish-TkM365AuditApp [[-AppPrefix] <String>] [[-CertThumbprint] <String>] [[-KeyExportPolicy] <String>] [[-VaultName] <String>] [-OverwriteVaultSecret] [-ReturnParamSplat] [-DoNotUseDomainSuffix] [<CommonParameters>]
| Name | Alias | Description | Required? | Pipeline Input | Default Value |
|---|---|---|---|---|---|
| AppPrefix | A short prefix \(2-4 alphanumeric characters) used to build the app name. Defaults to "Gtk" if not specified. Example app name: GraphToolKit-MSN-GraphApp-MyDomain-As-helpDesk | false | false | Gtk | |
| CertThumbprint | The thumbprint of an existing certificate in the current user's certificate store. If not provided, a new self-signed certificate is created. | false | false | ||
| KeyExportPolicy | Specifies whether the newly created certificate \(if no thumbprint is provided) is 'Exportable' or 'NonExportable'. Defaults to 'NonExportable'. | false | false | NonExportable | |
| VaultName | The SecretManagement vault name in which to store the app credentials. Defaults to "M365AuditAppLocalStore" if not specified. | false | false | M365AuditAppLocalStore | |
| OverwriteVaultSecret | If specified, overwrites an existing secret in the specified vault if it already exists. | false | false | False | |
| ReturnParamSplat | If specified, returns a parameter splat string for use in other functions, instead of the default PSCustomObject containing the app details. | false | false | False | |
| DoNotUseDomainSuffix | If specified, does not append the domain suffix to the app name. | false | false | False |
- None. This function does not accept pipeline input.
- By default, returns a PSCustomObject with details of the new app \(AppId, ObjectId, TenantId, certificate thumbprint, expiration, etc.). If -ReturnParamSplat is used, returns a parameter splat string.
Requires the Microsoft.Graph and ExchangeOnlineManagement modules for app creation and role assignment. The user must have sufficient privileges to create and manage applications in Azure AD, and to assign roles. After creation, admin consent may be required for the assigned permissions. Permissions required for app registration: 'Application.ReadWrite.All', 'DelegatedPermissionGrant.ReadWrite.All', 'Directory.ReadWrite.All', 'RoleManagement.ReadWrite.Directory' Permissions granted to the app: \(Exchange Administrator and Global Reader Roles are also added to the service principal.) 'AppCatalog.ReadWrite.All', 'Channel.Delete.All', 'ChannelMember.ReadWrite.All', 'ChannelSettings.ReadWrite.All', 'Directory.Read.All', 'Group.ReadWrite.All', 'Organization.Read.All', 'Policy.Read.All', 'Domain.Read.All', 'TeamSettings.ReadWrite.All', 'User.Read.All', 'Sites.Read.All', 'Sites.FullControl.All', 'Exchange.ManageAsApp'
EXAMPLE 1
Publish-TkM365AuditApp -AppPrefix "CS12" -ReturnParamSplat
Creates a new M365 Audit App with the prefix "CS12", returns a parameter splat, and stores
the credentials in the default vault.Publishes a new MEM \(Intune) Policy Manager App in Azure AD with read-only or read-write permissions.
Publish-TkMemPolicyManagerApp [-AppPrefix] <String> [[-CertThumbprint] <String>] [[-KeyExportPolicy] <String>] [[-VaultName] <String>] [-OverwriteVaultSecret] [-ReadWrite] [-ReturnParamSplat] [-DoNotUseDomainSuffix] [<CommonParameters>]
| Name | Alias | Description | Required? | Pipeline Input | Default Value |
|---|---|---|---|---|---|
| AppPrefix | A 2-4 character prefix used to build the application name \(e.g., CORP, MSN). This helps uniquely identify the app in Azure AD. | true | false | ||
| CertThumbprint | The thumbprint of an existing certificate in the current user's certificate store. If omitted, a new self-signed certificate is created. | false | false | ||
| KeyExportPolicy | Specifies whether the newly created certificate is 'Exportable' or 'NonExportable'. Defaults to 'NonExportable' if not specified. | false | false | NonExportable | |
| VaultName | The name of the SecretManagement vault in which to store the app credentials. Defaults to 'MemPolicyManagerLocalStore'. | false | false | MemPolicyManagerLocalStore | |
| OverwriteVaultSecret | If specified, overwrites any existing secret of the same name in the vault. | false | false | False | |
| ReadWrite | If specified, grants read-write MEM/Intune permissions. Otherwise, read-only permissions are granted. | false | false | False | |
| ReturnParamSplat | If specified, returns a parameter splat string for use in other functions. Otherwise, returns a PSCustomObject containing the app details. | false | false | False | |
| DoNotUseDomainSuffix | If specified, the function does not append the domain suffix to the app name. | false | false | False |
- None. This function does not accept pipeline input.
- By default, returns a PSCustomObject \(TkMemPolicyManagerAppParams) with details of the newly created app \(AppId, certificate thumbprint, tenant ID, etc.). If -ReturnParamSplat is used, returns a parameter splat string.
This function requires the Microsoft.Graph module for application creation and the user must have permissions in Azure AD to register and grant permissions to the application. After creation, admin consent may be needed to finalize the permission grants. Permissions required for app registration:: 'Application.ReadWrite.All', 'DelegatedPermissionGrant.ReadWrite.All', 'Directory.ReadWrite.All' Permissions required for read-only access: 'DeviceManagementConfiguration.Read.All', 'DeviceManagementApps.Read.All', 'DeviceManagementManagedDevices.Read.All', 'Policy.Read.ConditionalAccess', 'Policy.Read.All' Permissions required for read-write access: 'DeviceManagementConfiguration.ReadWrite.All', 'DeviceManagementApps.ReadWrite.All', 'DeviceManagementManagedDevices.ReadWrite.All', 'Policy.ReadWrite.ConditionalAccess', 'Policy.Read.All'
EXAMPLE 1
Publish-TkMemPolicyManagerApp -AppPrefix "CORP" -ReadWrite
Creates a new MEM Policy Manager App with read-write permissions, retrieves or
creates a certificate, and stores the credentials in the default vault.Sends an email using the Microsoft Graph API, either by retrieving app credentials from a local vault or by specifying them manually.
Send-TkEmailAppMessage -AppName <String> -To <String> -FromAddress <String> -Subject <String> -EmailBody <String> [-AttachmentPath <String[]>] [-VaultName <String>] [-WhatIf] [-Confirm] [<CommonParameters>]
Send-TkEmailAppMessage -AppId <String> -TenantId <String> -CertThumbprint <String> -To <String> -FromAddress <String> -Subject <String> -EmailBody <String> [-AttachmentPath <String[]>] [-WhatIf] [-Confirm] [<CommonParameters>]
| Name | Alias | Description | Required? | Pipeline Input | Default Value |
|---|---|---|---|---|---|
| AppName | [Vault Parameter Set Only\] The name of the pre-created Microsoft Graph Email App \(stored in GraphEmailAppLocalStore). Used only if the 'Vault' parameter set is chosen. The function retrieves the AppId, TenantId, and certificate thumbprint from the vault entry. | true | false | ||
| AppId | [Manual Parameter Set Only\] The Azure AD application \(client) ID to use for sending the email. Must be used together with TenantId and CertThumbprint in the 'Manual' parameter set. | true | false | ||
| TenantId | [Manual Parameter Set Only\] The Azure AD tenant ID \(GUID or domain name). Must be used together with AppId and CertThumbprint in the 'Manual' parameter set. | true | false | ||
| CertThumbprint | [Manual Parameter Set Only\] The certificate thumbprint \(in Cert:\CurrentUser\My) used for authenticating as the Azure AD app. Must be used together with AppId and TenantId in the 'Manual' parameter set. | true | false | ||
| To | The email address of the recipient. | true | false | ||
| FromAddress | The email address of the sender who is authorized to send email as configured in the Graph Email App. | true | false | ||
| Subject | The subject line of the email. | true | false | ||
| EmailBody | The body text of the email. | true | false | ||
| AttachmentPath | An array of file paths for any attachments to include in the email. Each path must exist as a leaf file. | false | false | ||
| VaultName | [Vault Parameter Set Only\] The name of the vault to retrieve the GraphEmailApp object. Default is 'GraphEmailAppLocalStore'. | false | false | GraphEmailAppLocalStore | |
| WhatIf | wi | false | false | ||
| Confirm | cf | false | false |
- This function requires the Microsoft.Graph, SecretManagement, SecretManagement.JustinGrote.CredMan, and MSAL.PS modules to be installed \(handled automatically via Initialize-TkModuleEnv). - For the 'Vault' parameter set, the local vault secret must store JSON properties including AppId, TenantID, and CertThumbprint. - Refer to https://learn.microsoft.com/en-us/graph/outlook-send-mail for details on sending mail via Microsoft Graph.
EXAMPLE 1
# Using the 'Vault' parameter set
Send-TkEmailAppMessage -AppName "GraphEmailApp" -To "[email protected]" -FromAddress "[email protected]" `
-Subject "Test Email" -EmailBody "This is a test email."
Retrieves the app's credentials (AppId, TenantId, CertThumbprint) from the local vault under the
secret name "GraphEmailApp" and sends an email.EXAMPLE 2
# Using the 'Manual' parameter set
Send-TkEmailAppMessage -AppId "00000000-1111-2222-3333-444444444444" -TenantId "contoso.onmicrosoft.com" `
-CertThumbprint "AABBCCDDEEFF11223344556677889900" -To "[email protected]" -FromAddress "[email protected]" `
-Subject "Manual Email" -EmailBody "Hello from Manual!"
Uses the provided AppId, TenantId, and CertThumbprint directly (no vault) to obtain a token and send an email.