sp_send_dbmail (Transact-SQL)

Aplica-se a:SQL ServerInstância Gerenciada de SQL do Azure

Envia uma mensagem de email aos destinatários especificados. A mensagem pode incluir um conjunto de resultados da consulta, anexos de arquivo ou ambos. Quando o email é colocado com êxito na fila Database Mail, sp_send_dbmail retorna o mailitem_id da mensagem. Esse procedimento armazenado está no msdb banco de dados.

Convenções de sintaxe de Transact-SQL

Sintaxe

sp_send_dbmail [ [ @profile_name = ] 'profile_name' ]
    [ , [ @recipients = ] 'recipients [ ; ...n ]' ]
    [ , [ @copy_recipients = ] 'copy_recipient [ ; ...n ]' ]
    [ , [ @blind_copy_recipients = ] 'blind_copy_recipient [ ; ...n ]' ]
    [ , [ @from_address = ] 'from_address' ]
    [ , [ @reply_to = ] 'reply_to' ]
    [ , [ @subject = ] N'subject' ]
    [ , [ @body = ] N'body' ]
    [ , [ @body_format = ] 'body_format' ]
    [ , [ @importance = ] 'importance' ]
    [ , [ @sensitivity = ] 'sensitivity' ]
    [ , [ @file_attachments = ] N'attachment [ ; ...n ]' ]
    [ , [ @query = ] N'query' ]
    [ , [ @execute_query_database = ] 'execute_query_database' ]
    [ , [ @attach_query_result_as_file = ] attach_query_result_as_file ]
    [ , [ @query_attachment_filename = ] N'query_attachment_filename' ]
    [ , [ @query_result_header = ] query_result_header ]
    [ , [ @query_result_width = ] query_result_width ]
    [ , [ @query_result_separator = ] 'query_result_separator' ]
    [ , [ @exclude_query_output = ] exclude_query_output ]
    [ , [ @append_query_error = ] append_query_error ]
    [ , [ @query_no_truncate = ] query_no_truncate ]
    [ , [ @query_result_no_padding = ] @query_result_no_padding ]
    [ , [ @mailitem_id = ] mailitem_id ] [ OUTPUT ]
[ ; ]

Argumentos

[ @profile_name = ] 'profile_name'

O nome do perfil do qual enviar a mensagem. O @profile_name é do tipo sysname, com um padrão de NULL. O @profile_name deve ser o nome de um perfil de Database Mail existente. Quando nenhuma @profile_name é especificada, sp_send_dbmail o usa o perfil privado padrão para o usuário atual. Se o usuário não tiver um perfil privado padrão, sp_send_dbmail usará o perfil público padrão para o msdb banco de dados. Se o usuário não tiver um perfil privado padrão e não houver um perfil público padrão para o banco de dados, @profile_name deverá ser especificado.

[ @recipients = ] 'recipients'

Uma lista delimitada por ponto e vírgula de endereços de email para os quais enviar a mensagem. A lista de destinatários é do tipo varchar(max). Embora esse parâmetro seja opcional, pelo menos um dos @recipients, @copy_recipients ou @blind_copy_recipients deve ser especificado ou sp_send_dbmail retorna um erro.

[ @copy_recipients = ] 'copy_recipients'

Uma lista delimitada por ponto e vírgula de endereços de email para os quais copiar a mensagem. A lista de destinatários de cópia é do tipo varchar(max). Embora esse parâmetro seja opcional, pelo menos um dos @recipients, @copy_recipients ou @blind_copy_recipients deve ser especificado ou sp_send_dbmail retorna um erro.

[ @blind_copy_recipients = ] 'blind_copy_recipients'

Uma lista delimitada por ponto e vírgula de endereços de email para os quais copiar a mensagem. A lista de destinatários de cópia cega é do tipo varchar(max). Embora esse parâmetro seja opcional, pelo menos um dos @recipients, @copy_recipients ou @blind_copy_recipients deve ser especificado ou sp_send_dbmail retorna um erro.

[ @from_address = ] 'from_address'

O valor do 'do endereço' da mensagem de email. Esse é um parâmetro opcional usado para substituir as configurações no perfil de email. Esse parâmetro é do tipo varchar(max). As configurações de segurança de SMTP determinarão se essas substituições serão aceitas. Se nenhum parâmetro for especificado, o padrão será NULL.

[ @reply_to = ] 'reply_to'

O valor do "endereço de resposta" da mensagem de email. Aceita apenas um endereço de email como um valor válido. Esse é um parâmetro opcional usado para substituir as configurações no perfil de email. Esse parâmetro é do tipo varchar(max). As configurações de segurança de SMTP determinarão se essas substituições serão aceitas. Se nenhum parâmetro for especificado, o padrão será NULL.

[ @subject = ] N'subject'

O assunto da mensagem de email. O assunto é do tipo nvarchar(255). Se nenhum assunto for especificado, o padrão será 'SQL Server Message'.

[ @body = ] N'body'

O corpo da mensagem de email. O corpo da mensagem é do tipo nvarchar(max), com um padrão de NULL.

[ @body_format = ] 'body_format'

O formato do corpo da mensagem. O parâmetro é do tipo varchar(20), com um padrão de NULL. Quando especificado, os cabeçalhos da mensagem de saída são definidos para indicar que o corpo da mensagem tem o formato especificado. O parâmetro pode conter um dos seguintes valores:

• TEXT (padrão)
• HTML

[ @importance = ] 'importance'

A importância da mensagem. O parâmetro é do tipo varchar(6). O parâmetro pode conter um dos seguintes valores:

• Low
• Normal (padrão)
• High

[ @sensitivity = ] 'sensibilidade'

A sensibilidade da mensagem. O parâmetro é do tipo varchar(12). O parâmetro pode conter um dos seguintes valores:

• Normal (padrão)
• Personal
• Private
• Confidential

[ @file_attachments = ] N'file_attachments'

Uma lista delimitada por ponto e vírgula de nomes de arquivo a serem anexados à mensagem de email. Os arquivos da lista devem ser especificados como caminhos absolutos. A lista de anexos é do tipo nvarchar(max). Por padrão, o Database Mail limita os anexos de arquivo a 1 MB por arquivo.

Importante

Esse parâmetro não está disponível no Instância Gerenciada de SQL do Azure, pois não pode acessar o sistema de arquivos local.

[ @query = ] N'query'

Uma consulta para executar. Os resultados da consulta podem ser anexados a um arquivo ou incluídos no corpo da mensagem de email. A consulta é do tipo nvarchar(max)e pode conter instruções Transact-SQL válidas. A consulta é executada em uma sessão separada, portanto, as variáveis locais na chamada sp_send_dbmail de script não estão disponíveis para a consulta.

Quando você usa o parâmetro @query, o usuário que executa sp_send_dbmail deve ser um logon SQL Server ou mapeado diretamente para a entidade de segurança (logon) do Azure AD ou do Windows Active Directory. Se o usuário for membro de um grupo Azure AD ou de um grupo do Windows Active Directory, ele não poderá executar a consulta. Isso ocorre devido a Instância Gerenciada de SQL do Azure representação e limitações de EXECUTE AS.

[ @execute_query_database = ] 'execute_query_database'

O contexto do banco de dados no qual o procedimento armazenado executa a consulta. O parâmetro é do tipo sysname, com um padrão do banco de dados atual. Esse parâmetro só será aplicável se @query for especificado.

[ @attach_query_result_as_file = ] attach_query_result_as_file

Especifica se o conjunto de resultados da consulta é retornado como um arquivo anexado. @attach_query_result_as_file é do tipo bit, com um padrão de 0.

Quando o valor é 0, os resultados da consulta são incluídos no corpo da mensagem de email, após o conteúdo do parâmetro @body . Quando o valor é 1, os resultados são retornados como um anexo. Esse parâmetro só será aplicável se @query for especificado.

[ @query_attachment_filename = ] N'query_attachment_filename'

Especifica o nome do arquivo a ser usado para o conjunto de resultados do anexo da consulta. @query_attachment_filename é do tipo nvarchar(255), com um padrão de NULL. Esse parâmetro é ignorado quando @attach_query_result_as_file é 0. Quando @attach_query_result_as_file é 1 e esse parâmetro é NULL, Database Mail cria um nome de arquivo arbitrário.

[ @query_result_header = ] query_result_header

Especifica se os resultados da consulta incluem cabeçalhos de coluna. O valor query_result_header é do tipo bit. Quando o valor é 1, os resultados da consulta contêm cabeçalhos de coluna. Quando o valor é 0, os resultados da consulta não incluem cabeçalhos de coluna. Esse parâmetro usa 1como padrão . Esse parâmetro só será aplicável se @query for especificado.

O erro a seguir pode ocorrer ao definir @query_result_header como 0 e definir @query_no_truncate como 1:

Msg 22050, Level 16, State 1, Line 12: Failed to initialize sqlcmd library with error number -2147024809.

[ @query_result_width = ] query_result_width

A largura da linha, em caracteres, a ser usada para formatar os resultados da consulta. O @query_result_width é do tipo int, com um padrão de 256. O valor fornecido deve ser entre 10 e 32767. Esse parâmetro só será aplicável se @query for especificado.

[ @query_result_separator = ] 'query_result_separator'

O caractere usado para separar as colunas na saída da consulta. O separador é do tipo char(1). O padrão é ' ' (espaço).

[ @exclude_query_output = ] exclude_query_output

Especifica se a saída da execução da consulta deve ser retornada na mensagem de email @exclude_query_output é bit, com um padrão de 0. Quando esse parâmetro é 0, a execução do sp_send_dbmail procedimento armazenado imprime a mensagem retornada como resultado da execução da consulta no console. Quando esse parâmetro é 1, a execução do sp_send_dbmail procedimento armazenado não imprime nenhuma das mensagens de execução de consulta no console.

[ @append_query_error = ] append_query_error

Especifica se o email deve ser enviado quando um erro retorna da consulta especificada no argumento @query . @append_query_error é bit, com um padrão de 0. Quando esse parâmetro é 1, Database Mail envia a mensagem de email e inclui a mensagem de erro de consulta no corpo da mensagem de email. Quando esse parâmetro é 0, Database Mail não envia a mensagem de email e sp_send_dbmail termina com o código 1de retorno , indicando falha.

[ @query_no_truncate = ] query_no_truncate

Especifica se a consulta deve ser executada com a opção que evita truncamento de tipos de dados de comprimento variável grande (varchar(max), nvarchar(max), varbinary(max), xml, text, ntext, image e tipos de dados definidos pelo usuário). Quando definido, os resultados da consulta não incluem cabeçalhos de coluna. O valor @query_no_truncate é do tipo bit. Quando o valor é 0 ou não especificado, as colunas na consulta são truncadas para 256 caracteres. Quando o valor é 1, as colunas na consulta não são truncadas. Esse parâmetro usa 0como padrão .

Observação

Quando usada com grandes quantidades de dados, a opção @query_no_truncate consome recursos adicionais e pode reduzir o desempenho do servidor.

[ @query_result_no_padding = ] query_result_no_padding

O tipo é bit. O padrão é 0. Quando você define como 1, os resultados da consulta não são adicionados, possivelmente reduzindo o tamanho do arquivo. Se você definir @query_result_no_padding como 1 e definir o parâmetro @query_result_width , o parâmetro @query_result_no_padding substituirá o parâmetro @query_result_width .

Nesse caso, nenhum erro ocorre.

O erro a seguir pode ocorrer ao definir @query_result_no_padding1 e fornecer um parâmetro para @query_no_truncate:

Msg 22050, Level 16, State 1, Line 0: Failed to execute the query because the @query_result_no_append and @query_no_truncate options are mutually exclusive.

Se você definir o @query_result_no_padding como 1 e definir o parâmetro @query_no_truncate , um erro será gerado.

[ @mailitem_id = ] mailitem_id [ OUTPUT ]

O parâmetro de saída opcional retorna o mailitem_id da mensagem. @mailitem_id é do tipo int.

Valores do código de retorno

Um código de retorno de 0 significa êxito. Qualquer outro valor significa falha. O código de erro da instrução que falhou é armazenado na @@ERROR variável .

Conjuntos de resultados

Com êxito, retorna a mensagem que "Email enfileirado".

Comentários

Antes do uso, Database Mail deve ser habilitado usando o Assistente de Configuração de Database Mail ou sp_configure.

sysmail_stop_spinterrompe Database Mail interrompendo os objetos do Service Broker que o programa externo usa. sp_send_dbmailainda aceita emails quando Database Mail é interrompido usando sysmail_stop_sp. Para iniciar Database Mail, use sysmail_start_sp.

Quando @profile não é especificado, sp_send_dbmail usa um perfil padrão. Se o usuário que envia a mensagem de email tiver um perfil particular padrão, o Database Mail irá utilizá-lo. Se o usuário não tiver nenhum perfil privado padrão, sp_send_dbmail usará o perfil público padrão. Se não houver nenhum perfil privado padrão para o usuário e nenhum perfil público padrão, sp_send_dbmail retornará um erro.

sp_send_dbmail não dá suporte a mensagens de email sem conteúdo. Para enviar uma mensagem de email, você deve especificar pelo menos um dos @body, @query, @file_attachments ou @subject. Caso contrário, sp_send_dbmail retornará um erro.

Database Mail usa o contexto de segurança do Microsoft Windows do usuário atual para controlar o acesso aos arquivos. Portanto, os usuários autenticados com SQL Server Autenticação não podem anexar arquivos usando @file_attachments. O Windows não permite que SQL Server forneçam credenciais de um computador remoto para outro computador remoto. Portanto, Database Mail pode não ser capaz de anexar arquivos de um compartilhamento de rede nos casos em que o comando é executado de um computador diferente do computador em que SQL Server executado.

Se @query e @file_attachments forem especificados e o arquivo não puder ser encontrado, a consulta ainda será executada, mas o email não será enviado.

Quando uma consulta é especificada, o conjunto de resultados é formatado como texto em linha. Dados binários no resultado são enviados em formato hexadecimal.

Os parâmetros @recipients, @copy_recipients e @blind_copy_recipients são listas delimitadas por ponto e vírgula de endereços de email. Pelo menos um desses parâmetros deve ser fornecido ou sp_send_dbmail retorna um erro.

Ao executar sem um contexto de sp_send_dbmail transação, Database Mail inicia e confirma uma transação implícita. Ao executar sp_send_dbmail de dentro de uma transação existente, Database Mail depende do usuário para confirmar ou reverter quaisquer alterações. Ele não inicia uma transação interna.

Permissões

Execute permissões para sp_send_dbmail o padrão para todos os membros da função de banco de dados DatabaseMailUser no msdb banco de dados. No entanto, quando o usuário que envia a mensagem não tem permissão para usar o perfil para a solicitação, sp_send_dbmail retorna um erro e não envia a mensagem.

Exemplos

a. Enviar uma mensagem de email

Este exemplo envia uma mensagem de email para seu amigo usando o endereço myfriend@adventure-works.comde email . O assunto da mensagem é Automated Success Message. O corpo da mensagem contém a sentença 'The stored procedure finished successfully'.

EXEC msdb.dbo.sp_send_dbmail
    @profile_name = 'Adventure Works Administrator',
    @recipients = 'yourfriend@adventure-works.com',
    @body = 'The stored procedure finished successfully.',
    @subject = 'Automated Success Message';

B. Enviar uma mensagem de email com os resultados de uma consulta

Este exemplo envia uma mensagem de email para seu amigo usando o endereço yourfriend@adventure-works.comde email . A mensagem tem o assunto Work Order Counte executa uma consulta que mostra o número de ordens de trabalho com menos DueDate de dois dias após 30 de abril de 2022. O Database Mail anexa o resultado como um arquivo de texto.

EXEC msdb.dbo.sp_send_dbmail
    @profile_name = 'Adventure Works Administrator',
    @recipients = 'yourfriend@adventure-works.com',
    @query = 'SELECT COUNT(*) FROM AdventureWorks2022.Production.WorkOrder
                  WHERE DueDate > ''2022-04-30''
                  AND  DATEDIFF(dd, ''2022-04-30'', DueDate) < 2',
    @subject = 'Work Order Count',
    @attach_query_result_as_file = 1;

C. Enviar uma mensagem de email HTML

Este exemplo envia uma mensagem de email para seu amigo usando o endereço yourfriend@adventure-works.comde email . A mensagem tem o assunto Work Order Liste contém um documento HTML que mostra os pedidos de trabalho com menos de DueDate dois dias após 30 de abril de 2022. O Database Mail envia a mensagem no formato HTML.

DECLARE @tableHTML NVARCHAR(MAX);

SET @tableHTML = N'<H1>Work Order Report</H1>' + N'<table border="1">'
    + N'<tr><th>Work Order ID</th><th>Product ID</th>'
    + N'<th>Name</th><th>Order Qty</th><th>Due Date</th>'
    + N'<th>Expected Revenue</th></tr>'
    + CAST((
            SELECT td = wo.WorkOrderID, '',
                td = p.ProductID, '',
                td = p.Name, '',
                td = wo.OrderQty, '',
                td = wo.DueDate, '',
                td = (p.ListPrice - p.StandardCost) * wo.OrderQty
            FROM AdventureWorks.Production.WorkOrder AS wo
            INNER JOIN AdventureWorks.Production.Product AS p
                ON wo.ProductID = p.ProductID
            WHERE DueDate > '2022-04-30'
                AND DATEDIFF(dd, '2022-04-30', DueDate) < 2
            ORDER BY DueDate ASC,
                (p.ListPrice - p.StandardCost) * wo.OrderQty DESC
            FOR XML PATH('tr'),
                TYPE
            ) AS NVARCHAR(MAX))
    + N'</table>';

EXEC msdb.dbo.sp_send_dbmail @recipients = 'yourfriend@adventure-works.com',
    @subject = 'Work Order List',
    @body = @tableHTML,
    @body_format = 'HTML';

Confira também

• Database Mail
• Objetos de configuração do Database Mail
• Procedimentos armazenados do Database Mail (Transact-SQL)
• sp_addrolemember (Transact-SQL)