Envie e-mails facilmente com o cmdlet Send-MailMessage do PowerShell – techsyncer

Para este cmdlet do PowerShell do dia, estamos cobrindo o cmdlet Send-MailMessage do PowerShell. Este cmdlet do PowerShell serve apenas para um propósito; enviar e-mails de várias maneiras diferentes.

Como existem tantas maneiras de enviar mensagens de e-mail com o cmdlet Send-MailMessage, vamos começar a cobrir todos os exemplos comuns que você pode encontrar. Neste artigo, vamos abordar muitos exemplos, desde os mais simples até alguns cenários que eu não desejo para ninguém!

Este post será um ótimo recurso para marcar, caso você se depare com situações em que precise enviar e-mails com o PowerShell e esqueça a sintaxe.

O Servidor SMTP

Todos os e-mails precisam passar por um servidor SMTP em algum lugar, por meio de um servidor e uma porta. Para especificar o servidor SMTP a ser usado, use um parâmetro chamado SMTPServer que permite especificar o servidor SMTP para estabelecer uma conexão e encaminhar e-mails. No entanto, isso não é obrigatório.

Se você não especificar um valor para o parâmetro SMTPServer, será usado o valor armazenado na variável de preferência $PSEmailServer. Você pode atribuir um valor a essa variável da mesma forma que faria com qualquer outra variável.

Assigning a value to the $PSEmailServer preference variable
PS51> $PSEmailServer = 'smtp.server.local'

No entanto, esta variável não persiste entre as sessões do PowerShell. Isso significa que você precisa defini-la toda vez que uma nova sessão do PowerShell é aberta. Por esse motivo, recomendo ou usá-la definindo-a acima da sua referência Send-MailMessage ou não defini-la de todo. Em vez disso, eu pessoalmente forneceria o valor do parâmetro SMTPServer. Dessa forma, você não precisa gerenciar uma variável externa que pode mudar.

PS51> Send-MailMessage -SmtpServer 'smtp.server.local'

Port

Por padrão, o valor que o cmdlet tentará enviar um email através do servidor SMTP é a porta 25. Este é SMTP simples e não criptografado. No entanto, hoje em dia, é mais comum enviar emails criptografados usando SSL/TLS (Abordaremos esses cenários posteriormente).

Se você precisar alterar a porta de 25, pode usar o parâmetro Port.

PS51> Send-MailMessage -SmtpServer 'smtp.server.local' -Port 587

Destinatários e Remetentes

Para enviar um email para diferentes destinatários por meio de métodos como os campos Para, Cc e Bcc, o cmdlet tem vários parâmetros para acomodar isso.

Os Parâmetros To, Cc e Bcc no Cmdlet Send-Mailmessage

O cmdlet tem três parâmetros, cada um suportando vários destinatários separados por vírgula chamados To, Cc e Bcc.

Você pode especificar endereços únicos como abaixo.

Sending email to one recipient via To, Cc and Bcc
PS51> Send-MailMessage -To joe@gmail.com -Cc bob@gmail.com -Bcc susie@hotmail.com -Subject 'this is a subject'

Ou você pode especificar vários destinatários para cada valor de parâmetro.

Sending email to multiple recipients via To, Cc and Bcc
PS51> Send-MailMessage -To joe@gmail.com, tony@mycompany.local -Cc bob@gmail.com, rick@othercompany.com -Bcc susie@hotmail.com,secret@fooorg.org -Subject 'this is a subject'

O Parâmetro From

Quando envia um e-mail, também pode especificar o parâmetro From, que definirá o cabeçalho “reply-to” no e-mail. Este parâmetro permite apenas um endereço. Se um destinatário optar por responder ao e-mail, este será o endereço de e-mail para o qual a resposta será enviada.

Sending email from an address
PS51> Send-MailMessage -From me@company.org -To joe@gmail.com -Subject 'this is a subject'

Por padrão, ao usar um endereço de e-mail, apenas o endereço de e-mail será exibido no campo FROM do destinatário. No entanto, se desejar especificar um nome ou algum tipo de rótulo como Caixa de Correio da Conta de Serviço, também pode especificar um nome e um e-mail assim:

Adam Bertram <adbertram@gmail.com>

Observe que o parâmetro Subject foi utilizado. Este parâmetro é sempre obrigatório. Você verá este parâmetro sendo utilizado em todos os exemplos.

Corpo

O parâmetro Body permite que especifique o que estará no corpo do e-mail. No mais simples, pode especificar qualquer texto que deseje, e o cmdlet o enviará como texto simples.

PS51> Send-MailMessage -From me@company.org -To joe@gmail.com -Subject 'this is a subject' -Body 'this is the body'

Envio de E-mails com Corpo em HTML

Também pode enviar um corpo de e-mail via HTML em vez de texto simples. Para fazer isso, use o mesmo parâmetro Body como faria com o texto simples, mas use HTML para a string e utilize o parâmetro de comutação BodyAsHtml.

Sending an HTML table in an email
$body = @'
<table style="width:100%">
  <tr>
    <th>Firstname</th>
    <th>Lastname</th> 
    <th>Age</th>
  </tr>
  <tr>
    <td>Jill</td>
    <td>Smith</td> 
    <td>50</td>
  </tr>
  <tr>
    <td>Eve</td>
    <td>Jackson</td> 
    <td>94</td>
  </tr>
</table>
'@

PS51> Send-MailMessage -From me@company.org -To joe@gmail.com -Subject 'this is a subject' -Body $body -BodyAsHtml

Observe no exemplo acima, eu envolvi a string do corpo em @' e '@. Isso é chamado de string de bloco. Isso permite que você defina strings longas geralmente vistas em corpos de e-mail que contêm quebras de linha. Strings de bloco preservam a formatação das strings e são uma ótima maneira de definir o corpo do e-mail, especialmente se for em HTML.

Codificação

Se você tiver caracteres especiais no assunto ou corpo do seu e-mail, pode usar o parâmetro Codificação. Este parâmetro permite que você codifique o assunto e o corpo do e-mail via o tipo de codificação especificado antes do envio.

Você tem algumas opções aqui:

ASCII (padrão)
UTF8
UTF7
UTF32
Unicode
BigEndianUnicode
Padrão
OEM

PS51> Send-MailMessage -From me@company.org -To joe@gmail.com -Subject 'this is a subject' -Body 'this is the body' -Encoding UTF8

Anexos

O cmdlet também pode anexar um ou mais arquivos. Para fazer isso, você pode usar o parâmetro Anexos e fornecer o caminho para o(s) arquivo(s) que você deseja anexar.

Attaching the C:\file.doc to an email
PS51> Send-MailMessage -From me@company.org -To joe@gmail.com -Subject 'this is a subject' -Body 'this is the body' -Attachments 'C:\file.doc'

Você também pode especificar vários anexos via uma coleção, separando-os com uma vírgula.

Attaching the C:\file.doc and D:\report.xlsx file to an email
PS51> Send-MailMessage -From me@company.org -To joe@gmail.com -Subject 'this is a subject' -Body 'this is the body' -Attachments 'C:\file.doc','D:\report.xlsx'

O parâmetro Anexos também permite que você encaminhe arquivos via cmdlets como Get-Item e Get-ChildItem para o cmdlet Send-MailMessage também.

PS51> Get-ChildItem -Path 'C:\MyFiles' | Send-MailMessage -From me@company.org -To joe@gmail.com -Subject 'this is a subject' -Body 'this is the body'

Email Seguro e Autenticado

Por padrão, o cmdlet envia e-mails via comunicação SMTP não criptografada na porta 25. No entanto, ele também oferece suporte para o envio de e-mails criptografados via SSL/TLS com nome de usuário e senha.

Se você tentar relatar e-mails por meio de um servidor SMTP que requer autenticação, o comando falha com uma mensagem de erro como a abaixo.

Error message when attempting to send unencrypted email.
The SMTP server requires a secure connection or the client was not
authenticated. The server response was: 5.7.0 Must issue a STARTTLS command first.

Para resolver isso, você deve primeiro especificar a porta (tipicamente 587 para TLS) e o parâmetro UseSsl. Isso indica ao cmdlet que ele deve tentar se conectar à porta 587 no servidor SMTP e criptografar a mensagem inteira. Normalmente (sempre?), você também precisará especificar o nome de usuário/senha para autenticar-se no servidor SMTP usando o parâmetro Credential.

PS51> $credential = Get-Credential
PS51> Send-MailMessage -From me@company.org -To joe@gmail.com -Subject 'this is a subject' -Body 'this is the body' -UseSsl -Port 587 -Credential $credential

Aqui estou obtendo um objeto de credencial (PSCredential) usando o cmdlet Get-Credential. Isso às vezes pode ser um problema porque é interativo, o que significa que ele para o script para solicitar um nome de usuário e uma senha. Para evitar isso, você poderia criar um objeto PSCredential na hora.

A common email example is to use Gmail. Using the knowledge you’ve gained above, you can now easily send email through Gmail using the smtp.gmail.com SMTP server as shown below.

$gmailCred = Get-Credential

$sendMailParams = @{
    From = '[email protected]' ## Deve ser gmail.com
    To = '[email protected]'
    Subject = 'some subject'
    Body = 'some body'
    SMTPServer = 'smtp.gmail.com'
    SMTPPort = 587
    UseSsl = $true
    Credential = $gmailCred
}

Send-MailMessage @sendMailParams

Atribuindo Prioridade ao E-mail

Embora seja uma característica do e-mail que eu pessoalmente gostaria que desaparecesse, você pode atribuir níveis de prioridade aos e-mails que envia usando o parâmetro Priority. Essa prioridade é então interpretada de várias maneiras pelo cliente de e-mail.

O Send-mailmessage permite que você atribua um e-mail com três prioridades diferentes.

Normal (padrão)
Alta
Baixa

Assigning a high-priority email
PS51> Send-MailMessage -From me@company.org -To joe@gmail.com -Subject 'this is a subject' -Body 'this is the body' -Priority High

Mas, por favor, pelo amor de Deus, não pense que todos os seus emails são de alta prioridade!

Notificações de Entrega

Finalmente, você pode especificar notificações de entrega para emails. As notificações de entrega são o que normalmente é conhecido como recibos de leitura em alguns clientes de email. As notificações de entrega permitem que você seja notificado se/quando o email for recebido pelo destinatário. No entanto, o destinatário ainda deve permitir isso.

Você tem quatro opções ao solicitar notificações de entrega.

Nenhuma (padrão)
EmSucesso (quando a entrega do email é bem-sucedida)
EmFalha (notificar se a entrega falhar)
Atraso (quando o email é atrasado via um servidor SMTP)

Você pode especificar uma opção de notificação de entrega usando o parâmetro DeliveryNotificationOptions.

Requesting a notification on delivery
PS51> Send-MailMessage -From me@company.org -To joe@gmail.com -Subject 'this is a subject' -Body 'this is the body' -DeliveryNotificationsOptions 'OnSuccess'

Você também pode solicitar várias notificações de entrega de uma vez, separando-as por vírgula.

Requesting a notification for all types
PS51> Send-MailMessage -From me@company.org -To joe@gmail.com -Subject 'this is a subject' -Body 'this is the body' -DeliveryNotificationsOptions 'OnSuccess','OnFailure','Delay'

Resumo

Neste post, você aprendeu tudo sobre o cmdlet Send-mailmessage e o que ele pode fazer. Cobrimos este cmdlet extensivamente usando todos os parâmetros que ele possui, juntamente com exemplos. Espero que este post possa servir como referência para você ao usar o cmdlet Send-mailmessage.

Leitura Adicional

Confira também alguns outros posts relacionados!