Nota
O acesso a esta página requer autorização. Pode tentar iniciar sessão ou alterar os diretórios.
O acesso a esta página requer autorização. Pode tentar alterar os diretórios.
Aplica-se a:
SQL ServerAzure SQL Managed Instance
Envia uma mensagem de email para os 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. Este procedimento armazenado está no msdb banco de dados.
Transact-SQL convenções de sintaxe
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 ]
[ ; ]
Arguments
@profile_name [ = ] «profile_name»
O nome do perfil a partir 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 nenhum @profile_name é especificado, 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 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 [ = ] «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 e-mail para os quais copiar a mensagem em carbono. 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 e-mail para os quais copiar ocultamente a mensagem. A lista de destinatários da 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 e-mail. Este é 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 SMTP determinam se essas substituições sã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 e-mail. Ele aceita apenas um endereço de e-mail como um valor válido. Este é 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 SMTP determinam se essas substituições são aceitas. Se nenhum parâmetro for especificado, o padrão será NULL.
@subject [ = ] N'sujeito'
O assunto da mensagem de email. O assunto é do tipo nvarchar(255). Se nenhum assunto for especificado, o padrão será 'Mensagem do SQL Server'.
@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) PersonalPrivateConfidential
@file_attachments [ = ] N'file_attachments'
Uma lista delimitada por ponto-e-vírgula de nomes de ficheiros a anexar à mensagem de correio eletrónico. Os arquivos na 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 como um ficheiro ou incluídos no corpo da mensagem de correio eletrónico. A consulta é do tipo nvarchar(max) e pode conter qualquer instrução Transact-SQL válida. 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 de sp_send_dbmail segurança que executa deve ser conectada como um indivíduo, não como parte de um grupo, seja uma ID do Microsoft Entra (anteriormente Azure Ative Directory) ou um grupo do Windows Ative Directory. Os logons do SQL Server, as identidades do Windows e as 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 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. Este 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. Este 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 de consulta.
@query_attachment_filename é do tipo nvarchar(255), com um padrão de NULL. Este parâmetro é ignorado quando @attach_query_result_as_file é 0. Quando @attach_query_result_as_file é 1 e esse parâmetro é NULL, 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. O padrão desse parâmetro é 1. Este parâmetro só é aplicável se @query for especificado.
O seguinte erro pode ocorrer ao definir @query_result_header0 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 estar entre 10 e 32767. Este parâmetro só é aplicável se @query for especificado.
@query_result_separator [ = ] «query_result_separator»
O caractere usado para separar 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. O padrão desse parâmetro é 0.
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. A predefiniçã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 @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 .
Neste caso, não ocorre nenhum erro.
O seguinte erro pode ocorrer ao definir @query_result_no_padding e 1 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 [ REALIZAÇÃO ]
O parâmetro de saída opcional retorna o mailitem_id da mensagem.
@mailitem_id é do tipo int.
Valores de 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
Quando for bem-sucedido, retorna a mensagem "Email enfileirado".
Observações
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 é interrompido 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 privado padrão, o Database Mail usará esse perfil. Se o usuário não tiver um 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 suporta mensagens de correio eletrónico sem conteúdo. Para enviar uma mensagem de email, você deve especificar pelo menos uma das @body, @query, @file_attachments ou @subject. Caso contrário, sp_send_dbmail retorna um erro.
O Database Mail é executado no contexto de segurança da conta de serviço do SQL Server. 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 a partir 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 embutido. Os 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 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.
Permissions
Execute permissões padrão sp_send_dbmail para todos os membros da função de banco de dados DatabaseMailUserRole 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.
Examples
A. Enviar uma mensagem de correio eletrónico
Este exemplo envia uma mensagem de email para seu amigo usando o endereço myfriend@adventure-works.comde email . A mensagem tem o assunto Automated Success Message. O corpo da mensagem contém a frase The stored procedure finished successfully.
EXECUTE 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 correio eletrónico 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 Count, e executa uma consulta que mostra o número de ordens de serviço com menos de dois dias após 30 DueDate de abril de 2022. O Database Mail anexa o resultado como um arquivo de texto.
EXECUTE 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 correio eletrónico 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 List, e contém um documento HTML que mostra as ordens de serviço com menos de dois dias após 30 DueDate de abril de 2022. O Database Mail envia a mensagem em 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>';
EXECUTE msdb.dbo.sp_send_dbmail
@recipients = 'yourfriend@adventure-works.com',
@subject = 'Work Order List',
@body = @tableHTML,
@body_format = 'HTML';