Set-DbaDbMailAccount

Synopsis

Modifies an existing Database Mail account on SQL Server

Description

Modifies the configuration of an existing Database Mail account including account properties (display name, email address, description) and mail server settings (SMTP server name, port, SSL, and authentication). This command is useful for updating Database Mail accounts to use cloud email services like Office 365 or Gmail, or for updating credentials when passwords change.

Syntax

Set-DbaDbMailAccount
    [[-SqlInstance] <DbaInstanceParameter[]>]
    [[-SqlCredential] <PSCredential>]
    [[-Account] <String[]>]
    [[-InputObject] <MailAccount[]>]
    [[-DisplayName] <String>]
    [[-Description] <String>]
    [[-EmailAddress] <String>]
    [[-ReplyToAddress] <String>]
    [[-NewMailServerName] <String>]
    [[-Port] <Int32>]
    [-EnableSSL]
    [-UseDefaultCredentials]
    [[-UserName] <String>]
    [[-Password] <SecureString>]
    [-EnableException]
    [-WhatIf]
    [-Confirm]
    [<CommonParameters>]

Examples

Example: 1

PS C:\> Set-DbaDbMailAccount -SqlInstance sql2017 -Account 'MaintenanceAlerts' -Port 587 -EnableSSL

Updates the MaintenanceAlerts mail account on sql2017 to use port 587 with SSL enabled.

Example: 2

PS C:\> $splatAccount = @{
>>     SqlInstance       = 'sql2017'
>>     Account           = 'Alerts'
>>     NewMailServerName = 'smtp.office365.com'
>>     Port              = 587
>>     EnableSSL         = $true
>>     UserName          = '[email protected]'
>>     Password          = (ConvertTo-SecureString 'app-password' -AsPlainText -Force)
>> }
PS C:\> Set-DbaDbMailAccount @splatAccount

Migrates the Alerts mail account on sql2017 to Office 365 with SSL and basic authentication.

Example: 3

PS C:\> Get-DbaDbMailAccount -SqlInstance sql2017 -Account 'MaintenanceAlerts' | Set-DbaDbMailAccount -Port 25 -EnableSSL:$false

Uses the pipeline to update the MaintenanceAlerts account to use port 25 with SSL disabled.

Example: 4

PS C:\> Set-DbaDbMailAccount -SqlInstance sql2017 -Account 'DomainRelay' -UseDefaultCredentials

Configures the DomainRelay mail account to use Windows integrated authentication.

Optional Parameters

-SqlInstance

The target SQL Server instance or instances.

-SqlCredential

Login to the target instance using alternative credentials. Accepts PowerShell credentials (Get-Credential).
Windows Authentication, SQL Server Authentication, Active Directory - Password, and Active Directory - Integrated are all supported.
For MFA support, please use Connect-DbaInstance.

-Account

Specifies one or more Database Mail account names to modify. Used in combination with -SqlInstance.

-InputObject

Accepts MailAccount objects from the pipeline, typically from Get-DbaDbMailAccount. Allows you to chain Database Mail commands together.

-DisplayName

Updates the friendly name that appears in the ‘From’ field of outgoing emails.

-Description

Updates the optional documentation text describing the account’s purpose and usage.

-EmailAddress

Updates the sender email address that appears in outgoing messages from this Database Mail account.

-ReplyToAddress

Updates the alternate email address for replies when different from the sender address.

-NewMailServerName

Renames or replaces the SMTP server hostname for the mail account. Use this to migrate to a different SMTP server.

-Port

Updates the TCP port number used to connect to the SMTP server. Common values are 25 (standard SMTP), 465 (SMTPS), and 587 (SMTP with STARTTLS).
Use 587 for Office 365 and Gmail which require STARTTLS.

-EnableSSL

Enables or disables SSL/TLS encryption for the SMTP connection. Use -EnableSSL:$false to explicitly disable SSL.

-UseDefaultCredentials

Enables or disables Windows integrated authentication (the SQL Server service account credentials) for SMTP authentication.
Use -UseDefaultCredentials:$false to explicitly disable Windows authentication.

-UserName

Updates the username for SMTP authentication. For Office 365, use the full email address.

-Password

Updates the password for SMTP authentication as a SecureString.
Create with: ConvertTo-SecureString ‘yourpassword’ -AsPlainText -Force

-EnableException

By default, when something goes wrong we try to catch it, interpret it and give you a friendly warning message.
This avoids overwhelming you with “sea of red” exceptions, but is inconvenient because it basically disables advanced scripting.
Using this switch turns this “nice by default” feature off and enables you to catch exceptions with your own try/catch.

-WhatIf

If this switch is enabled, no actions are performed but informational messages will be displayed that explain what would happen if the command were to run.

-Confirm

If this switch is enabled, you will be prompted for confirmation before executing any operations that change state.

Outputs

Microsoft.SqlServer.Management.Smo.Mail.MailAccount

Returns the updated MailAccount object from the specified SQL Server instance.

Default display properties (via Select-DefaultView):

• ComputerName: The computer name of the SQL Server instance
• InstanceName: The SQL Server instance name
• SqlInstance: The full SQL Server instance name (computer\instance)
• Id: Unique identifier for the mail account
• Name: Name of the mail account
• DisplayName: Friendly name that appears in the ‘From’ field of emails
• Description: Description of the account’s purpose
• EmailAddress: Sender email address for outgoing messages
• ReplyToAddress: Alternate email address for replies
• IsBusyAccount: Boolean indicating if the account is currently processing emails
• MailServers: Collection of mail servers associated with this account