|
| 1 | +function Set-DbaDbMailAccount { |
| 2 | + <# |
| 3 | + .SYNOPSIS |
| 4 | + Modifies an existing Database Mail account on SQL Server |
| 5 | +
|
| 6 | + .DESCRIPTION |
| 7 | + 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. |
| 8 | +
|
| 9 | + .PARAMETER SqlInstance |
| 10 | + The target SQL Server instance or instances. |
| 11 | +
|
| 12 | + .PARAMETER SqlCredential |
| 13 | + Login to the target instance using alternative credentials. Accepts PowerShell credentials (Get-Credential). |
| 14 | +
|
| 15 | + Windows Authentication, SQL Server Authentication, Active Directory - Password, and Active Directory - Integrated are all supported. |
| 16 | +
|
| 17 | + For MFA support, please use Connect-DbaInstance. |
| 18 | +
|
| 19 | + .PARAMETER Account |
| 20 | + Specifies one or more Database Mail account names to modify. Used in combination with -SqlInstance. |
| 21 | +
|
| 22 | + .PARAMETER InputObject |
| 23 | + Accepts MailAccount objects from the pipeline, typically from Get-DbaDbMailAccount. Allows you to chain Database Mail commands together. |
| 24 | +
|
| 25 | + .PARAMETER DisplayName |
| 26 | + Updates the friendly name that appears in the 'From' field of outgoing emails. |
| 27 | +
|
| 28 | + .PARAMETER Description |
| 29 | + Updates the optional documentation text describing the account's purpose and usage. |
| 30 | +
|
| 31 | + .PARAMETER EmailAddress |
| 32 | + Updates the sender email address that appears in outgoing messages from this Database Mail account. |
| 33 | +
|
| 34 | + .PARAMETER ReplyToAddress |
| 35 | + Updates the alternate email address for replies when different from the sender address. |
| 36 | +
|
| 37 | + .PARAMETER NewMailServerName |
| 38 | + Renames or replaces the SMTP server hostname for the mail account. Use this to migrate to a different SMTP server. |
| 39 | +
|
| 40 | + .PARAMETER Port |
| 41 | + 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). |
| 42 | + Use 587 for Office 365 and Gmail which require STARTTLS. |
| 43 | +
|
| 44 | + .PARAMETER EnableSSL |
| 45 | + Enables or disables SSL/TLS encryption for the SMTP connection. Use -EnableSSL:$false to explicitly disable SSL. |
| 46 | +
|
| 47 | + .PARAMETER UseDefaultCredentials |
| 48 | + Enables or disables Windows integrated authentication (the SQL Server service account credentials) for SMTP authentication. |
| 49 | + Use -UseDefaultCredentials:$false to explicitly disable Windows authentication. |
| 50 | +
|
| 51 | + .PARAMETER UserName |
| 52 | + Updates the username for SMTP authentication. For Office 365, use the full email address. |
| 53 | +
|
| 54 | + .PARAMETER Password |
| 55 | + Updates the password for SMTP authentication as a SecureString. |
| 56 | + Create with: ConvertTo-SecureString 'yourpassword' -AsPlainText -Force |
| 57 | +
|
| 58 | + .PARAMETER WhatIf |
| 59 | + 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. |
| 60 | +
|
| 61 | + .PARAMETER Confirm |
| 62 | + If this switch is enabled, you will be prompted for confirmation before executing any operations that change state. |
| 63 | +
|
| 64 | + .PARAMETER EnableException |
| 65 | + By default, when something goes wrong we try to catch it, interpret it and give you a friendly warning message. |
| 66 | + This avoids overwhelming you with "sea of red" exceptions, but is inconvenient because it basically disables advanced scripting. |
| 67 | + Using this switch turns this "nice by default" feature off and enables you to catch exceptions with your own try/catch. |
| 68 | +
|
| 69 | + .NOTES |
| 70 | + Tags: DatabaseMail, DbMail, Mail |
| 71 | + Author: the dbatools team + Claude |
| 72 | +
|
| 73 | + Website: https://dbatools.io |
| 74 | + Copyright: (c) 2018 by dbatools, licensed under MIT |
| 75 | + License: MIT https://opensource.org/licenses/MIT |
| 76 | +
|
| 77 | + .LINK |
| 78 | + https://dbatools.io/Set-DbaDbMailAccount |
| 79 | +
|
| 80 | + .OUTPUTS |
| 81 | + Microsoft.SqlServer.Management.Smo.Mail.MailAccount |
| 82 | +
|
| 83 | + Returns the updated MailAccount object from the specified SQL Server instance. |
| 84 | +
|
| 85 | + Default display properties (via Select-DefaultView): |
| 86 | + - ComputerName: The computer name of the SQL Server instance |
| 87 | + - InstanceName: The SQL Server instance name |
| 88 | + - SqlInstance: The full SQL Server instance name (computer\instance) |
| 89 | + - Id: Unique identifier for the mail account |
| 90 | + - Name: Name of the mail account |
| 91 | + - DisplayName: Friendly name that appears in the 'From' field of emails |
| 92 | + - Description: Description of the account's purpose |
| 93 | + - EmailAddress: Sender email address for outgoing messages |
| 94 | + - ReplyToAddress: Alternate email address for replies |
| 95 | + - IsBusyAccount: Boolean indicating if the account is currently processing emails |
| 96 | + - MailServers: Collection of mail servers associated with this account |
| 97 | +
|
| 98 | + .EXAMPLE |
| 99 | + PS C:\> Set-DbaDbMailAccount -SqlInstance sql2017 -Account 'MaintenanceAlerts' -Port 587 -EnableSSL |
| 100 | +
|
| 101 | + Updates the MaintenanceAlerts mail account on sql2017 to use port 587 with SSL enabled. |
| 102 | +
|
| 103 | + .EXAMPLE |
| 104 | + PS C:\> $splatAccount = @{ |
| 105 | + >> SqlInstance = 'sql2017' |
| 106 | + >> Account = 'Alerts' |
| 107 | + >> NewMailServerName = 'smtp.office365.com' |
| 108 | + >> Port = 587 |
| 109 | + >> EnableSSL = $true |
| 110 | + >> UserName = 'alerts@company.com' |
| 111 | + >> Password = (ConvertTo-SecureString 'app-password' -AsPlainText -Force) |
| 112 | + >> } |
| 113 | + PS C:\> Set-DbaDbMailAccount @splatAccount |
| 114 | +
|
| 115 | + Migrates the Alerts mail account on sql2017 to Office 365 with SSL and basic authentication. |
| 116 | +
|
| 117 | + .EXAMPLE |
| 118 | + PS C:\> Get-DbaDbMailAccount -SqlInstance sql2017 -Account 'MaintenanceAlerts' | Set-DbaDbMailAccount -Port 25 -EnableSSL:$false |
| 119 | +
|
| 120 | + Uses the pipeline to update the MaintenanceAlerts account to use port 25 with SSL disabled. |
| 121 | +
|
| 122 | + .EXAMPLE |
| 123 | + PS C:\> Set-DbaDbMailAccount -SqlInstance sql2017 -Account 'DomainRelay' -UseDefaultCredentials |
| 124 | +
|
| 125 | + Configures the DomainRelay mail account to use Windows integrated authentication. |
| 126 | +
|
| 127 | + #> |
| 128 | + [CmdletBinding(SupportsShouldProcess, ConfirmImpact = "Medium")] |
| 129 | + param ( |
| 130 | + [DbaInstanceParameter[]]$SqlInstance, |
| 131 | + [PSCredential]$SqlCredential, |
| 132 | + [string[]]$Account, |
| 133 | + [Parameter(ValueFromPipeline)] |
| 134 | + [Microsoft.SqlServer.Management.Smo.Mail.MailAccount[]]$InputObject, |
| 135 | + [string]$DisplayName, |
| 136 | + [string]$Description, |
| 137 | + [string]$EmailAddress, |
| 138 | + [string]$ReplyToAddress, |
| 139 | + [string]$NewMailServerName, |
| 140 | + [int]$Port, |
| 141 | + [switch]$EnableSSL, |
| 142 | + [switch]$UseDefaultCredentials, |
| 143 | + [string]$UserName, |
| 144 | + [System.Security.SecureString]$Password, |
| 145 | + [switch]$EnableException |
| 146 | + ) |
| 147 | + process { |
| 148 | + foreach ($instance in $SqlInstance) { |
| 149 | + $InputObject += Get-DbaDbMailAccount -SqlInstance $instance -SqlCredential $SqlCredential -Account $Account -EnableException:$EnableException |
| 150 | + } |
| 151 | + |
| 152 | + foreach ($mailAccount in $InputObject) { |
| 153 | + $instanceName = $mailAccount.SqlInstance |
| 154 | + if (-not $instanceName) { |
| 155 | + $instanceName = $mailAccount.Parent.Parent.DomainInstanceName |
| 156 | + } |
| 157 | + |
| 158 | + if ($Pscmdlet.ShouldProcess($instanceName, "Updating mail account $($mailAccount.Name)")) { |
| 159 | + $accountChanged = $false |
| 160 | + |
| 161 | + try { |
| 162 | + if (Test-Bound -ParameterName DisplayName) { $mailAccount.DisplayName = $DisplayName; $accountChanged = $true } |
| 163 | + if (Test-Bound -ParameterName Description) { $mailAccount.Description = $Description; $accountChanged = $true } |
| 164 | + if (Test-Bound -ParameterName EmailAddress) { $mailAccount.EmailAddress = $EmailAddress; $accountChanged = $true } |
| 165 | + if (Test-Bound -ParameterName ReplyToAddress) { $mailAccount.ReplyToAddress = $ReplyToAddress; $accountChanged = $true } |
| 166 | + |
| 167 | + if ($accountChanged) { |
| 168 | + $mailAccount.Alter() |
| 169 | + } |
| 170 | + } catch { |
| 171 | + Stop-Function -Message "Failure updating account properties for $($mailAccount.Name) on $instanceName" -Target $mailAccount -ErrorRecord $_ -Continue |
| 172 | + } |
| 173 | + |
| 174 | + try { |
| 175 | + $mailServerObj = $mailAccount.MailServers | Select-Object -First 1 |
| 176 | + |
| 177 | + if ($null -ne $mailServerObj) { |
| 178 | + if (Test-Bound -ParameterName NewMailServerName) { $mailServerObj.Rename($NewMailServerName) } |
| 179 | + if (Test-Bound -ParameterName Port) { $mailServerObj.Port = $Port } |
| 180 | + if (Test-Bound -ParameterName EnableSSL) { $mailServerObj.EnableSsl = $EnableSSL.IsPresent } |
| 181 | + if (Test-Bound -ParameterName UseDefaultCredentials) { $mailServerObj.UseDefaultCredentials = $UseDefaultCredentials.IsPresent } |
| 182 | + if (Test-Bound -ParameterName UserName) { $mailServerObj.UserName = $UserName } |
| 183 | + if (Test-Bound -ParameterName Password) { |
| 184 | + $mailServerObj.Password = (New-Object System.Net.NetworkCredential("", $Password)).Password |
| 185 | + } |
| 186 | + $mailServerObj.Alter() |
| 187 | + } |
| 188 | + } catch { |
| 189 | + Stop-Function -Message "Failure updating mail server for account $($mailAccount.Name) on $instanceName" -Target $mailAccount -ErrorRecord $_ -Continue |
| 190 | + } |
| 191 | + |
| 192 | + $mailAccount.Refresh() |
| 193 | + Add-Member -Force -InputObject $mailAccount -MemberType NoteProperty -Name ComputerName -value $mailAccount.Parent.Parent.ComputerName |
| 194 | + Add-Member -Force -InputObject $mailAccount -MemberType NoteProperty -Name InstanceName -value $mailAccount.Parent.Parent.ServiceName |
| 195 | + Add-Member -Force -InputObject $mailAccount -MemberType NoteProperty -Name SqlInstance -value $mailAccount.Parent.Parent.DomainInstanceName |
| 196 | + $mailAccount | Select-DefaultView -Property ComputerName, InstanceName, SqlInstance, Id, Name, DisplayName, Description, EmailAddress, ReplyToAddress, IsBusyAccount, MailServers |
| 197 | + } |
| 198 | + } |
| 199 | + } |
| 200 | +} |
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?v=4&size=40){kind=avatar}
0 commit comments