sp_send_dbmail (Transact-SQL)

Artigo
12/20/2023

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

Envia uma mensagem de email aos destinatários especificados. A mensagem pode incluir um conjunto de resultados de consulta, anexos de arquivo ou ambos. Quando o email é colocado com êxito na fila do 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 existente do Database Mail. Quando nenhuma @profile_name é especificada, sp_send_dbmail 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 use 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 [ = ] 'destinatários'

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 copiar a mensagem. A lista de destinatários da 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 copiar ocultamente a mensagem. A lista de destinatários de cópia oculta é 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 'endereço de' da mensagem de email. Esse é um parâmetro opcional usado para substituir as configurações no perfil de email. Este 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 da "resposta ao endereço" 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. Este 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'sujeito'

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

@body [ = ] N'corpo'

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:

TEXTO (padrão)
HTML

@importance [ = ] 'importância'

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 na Instância Gerenciada SQL do Azure, porque não pode acessar o sistema de arquivos local.

@query [ = ] N'consulta'

Uma consulta a ser executada. 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 quaisquer 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, a entidade executada sp_send_dbmail deve estar conectada como um indivíduo, não como parte de um grupo, seja uma ID do Microsoft Entra (anteriormente Azure Active Directory) ou um grupo do Windows Active Directory. Logons do SQL Server, identidades do Windows e identidades do Microsoft Entra podem executar a consulta, mas os membros do grupo não podem, devido à representação da Instância Gerenciada SQL do Azure e às limitações 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ó é 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ó é 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 é e esse parâmetro é 1NULL, o 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 tem como 1padrão . Esse parâmetro só é aplicável se @query for especificado.

O seguinte erro pode ocorrer ao definir @query_result_header e 0 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 estar entre 10 e 32767. Esse parâmetro só é 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, o 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, o 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 o 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 definidos, 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 truncam para 256 caracteres. Quando o valor é 1, as colunas na consulta não são truncadas. Esse parâmetro tem como 0padrão .

Observação

Quando usada com grandes quantidades de dados, a opção @query_no_truncate consome recursos adicionais e pode diminuir 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 acolchoados, possivelmente reduzindo o tamanho do arquivo. Se você definir como e definir @query_result_no_padding o parâmetro @query_result_width, o parâmetro @query_result_no_padding substituirá o parâmetro @query_result_width.1

Nesse caso, nenhum erro ocorre.

O seguinte erro 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 e definir o parâmetro @query_no_truncate, um erro será gerado.1

@mailitem_id [ = ] mailitem_id [ SAÍDA ]

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 significa 0 sucesso. Qualquer outro valor significa falha. O código de erro para a instrução que falhou é armazenado na @@ERROR variável.

Conjunto de resultados

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

Comentários

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

sysmail_stop_sp interrompe o Database Mail interrompendo os objetos do Service Broker que o programa externo usa. sp_send_dbmail ainda aceita email quando o Database Mail parar de usar sysmail_stop_spo . Para iniciar o 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 oferece 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.

O 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 a Autenticação do SQL Server não podem anexar arquivos usando @file_attachments. O Windows não permite que o SQL Server forneça credenciais de um computador remoto para outro computador remoto. Portanto, o 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 o 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 de endereços de email delimitadas por ponto-e-vírgula. Pelo menos um desses parâmetros deve ser fornecido ou sp_send_dbmail retorna um erro.

Ao executar sp_send_dbmail sem um contexto de transação, o Database Mail inicia e confirma uma transação implícita. Ao executar sp_send_dbmail a partir de uma transação existente, o 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 padrão sp_send_dbmail 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

R. 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 serviço com menos de dois dias após 30 de abril de DueDate 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 as ordens de serviço com menos de dois dias após 30 de abril de DueDate 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';

sp_send_dbmail (Transact-SQL)

Sintaxe

Argumentos

@profile_name [ = ] 'profile_name'

@recipients [ = ] 'destinatários'

@copy_recipients [ = ] 'copy_recipients'

@blind_copy_recipients [ = ] 'blind_copy_recipients'

@from_address [ = ] 'from_address'

@reply_to [ = ] 'reply_to'

@subject [ = ] N'sujeito'

@body [ = ] N'corpo'

@body_format [ = ] 'body_format'

@importance [ = ] 'importância'

@sensitivity [ = ] 'sensibilidade'

@file_attachments [ = ] N'file_attachments'

@query [ = ] N'consulta'

@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 [ SAÍDA ]

Valores do código de retorno

Conjunto de resultados

Comentários

Permissões

Exemplos

R. Enviar uma mensagem de email

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

C. Enviar uma mensagem de email HTML

Conteúdo relacionado

Comentários

Comentários

Recursos adicionais