sp_send_dbmail (Transact-SQL)

项目
08/21/2024

向指定收件人发送电子邮件。邮件可能包括查询结果集、文件附件或两者。成功将邮件放置在数据库邮件队列中时，sp_send_dbmail返回mailitem_id邮件。此存储过程位于 msdb 数据库中。

语法

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 ]
[ ; ]

参数

[ @profile_name = ] 'profile_name'

要从中发送消息的配置文件的名称。 @profile_name的类型为 sysname，默认值为 NULL. @profile_name必须是现有数据库邮件配置文件的名称。如果未 指定@profile_name ， sp_send_dbmail 请使用当前用户的默认专用配置文件。如果用户没有默认的专用配置文件， sp_send_dbmail 请使用数据库的默认公共配置文件 msdb 。如果用户没有默认的专用配置文件，并且没有数据库的默认公共配置文件， 则必须指定@profile_name 。

[ @recipients = ] 'recipients'

要向其发送邮件的电子邮件地址的分号分隔列表。收件人列表的类型为 varchar（max）。 尽管此参数是可选的，但必须指定至少一个 @recipients、 @copy_recipients或 @blind_copy_recipients ，或 sp_send_dbmail 返回错误。

[ @copy_recipients = ] 'copy_recipients'

要将邮件复制到的以分号分隔的电子邮件地址列表。复制收件人列表的类型为 varchar（max）。 尽管此参数是可选的，但必须指定至少一个 @recipients、 @copy_recipients或 @blind_copy_recipients ，或 sp_send_dbmail 返回错误。

[ @blind_copy_recipients = ] 'blind_copy_recipients'

以分号分隔的电子邮件地址列表，用于盲件抄送邮件。盲复制收件人列表的类型为 varchar（max）。 尽管此参数是可选的，但必须指定至少一个 @recipients、 @copy_recipients或 @blind_copy_recipients ，或 sp_send_dbmail 返回错误。

[ @from_address = ] 'from_address'

电子邮件的“发件人地址”的值。这是一个可选参数，用于覆盖邮件配置文件中的设置。此参数的类型为 varchar（max）。 SMTP 安全设置决定是否接受这些覆盖。如果未指定任何参数，则默认值为 NULL。

[ @reply_to = ] 'reply_to'

电子邮件的“回复地址”的值。它只接受一个电子邮件地址作为有效值。这是一个可选参数，用于覆盖邮件配置文件中的设置。此参数的类型为 varchar（max）。 SMTP 安全设置决定是否接受这些覆盖。如果未指定任何参数，则默认值为 NULL。

[ @subject = ] N'subject'

电子邮件的主题。主题的类型为 nvarchar（255）。 如果未指定主题，则默认为“SQL Server 消息”。

[ @body = ] N'body'

电子邮件的正文。消息正文的类型为 nvarchar（max），默认值为 NULL.

[ @body_format = ] 'body_format'

消息正文的格式。参数的类型 为 varchar（20），默认值为 NULL. 如果已指定，则待发邮件的标头设置会指示邮件正文具有指定格式。该参数可能包含以下值之一：

TEXT （默认值）
HTML

[ @importance = ] 'importance'

消息的重要性。参数的类型为 varchar（6）。 该参数可能包含以下值之一：

Low
Normal（默认值）
High

[ @sensitivity = ] 'sensitivity'

消息的敏感度。参数的类型为 varchar（12）。 该参数可能包含以下值之一：

Normal（默认值）
Personal
Private
Confidential

[ @file_attachments = ] N'file_attachments'

要附加到电子邮件的文件名的以分号分隔的列表。必须使用绝对路径指定列表中的文件。附件列表的类型为 nvarchar（max）。 默认情况下，数据库邮件会将文件附件限制在每个文件 1 MB 大小。

重要

此参数在Azure SQL 托管实例中不可用，因为它无法访问本地文件系统。

[ @query = ] N'query'

要执行的查询。查询结果可以作为文件附加，或包含在电子邮件的正文中。查询的类型 为 nvarchar（max），可以包含任何有效的 Transact-SQL 语句。查询在单独的会话中执行，因此调用脚本 sp_send_dbmail 中的局部变量对查询不可用。

使用 @query 参数时，执行的 sp_send_dbmail 主体必须作为单个（而不是作为组的一部分）进行连接，无论是Microsoft Entra ID（前 Azure Active Directory）还是 Windows Active Directory 组。 SQL Server 登录名、Windows 标识和Microsoft Entra 标识可以执行查询，但由于Azure SQL 托管实例模拟和 EXECUTE AS 限制，组成员无法执行。

[ @execute_query_database = ] 'execute_query_database'

在其中运行查询的存储过程的数据库上下文。参数的类型为 sysname，默认为当前数据库。仅当指定了@query时，此参数才适用。

[ @attach_query_result_as_file = ] attach_query_result_as_file

指定查询结果集是否作为附件返回。 @attach_query_result_as_file的类型为位，默认值为 0.

如果值为值0，则查询结果包含在电子邮件正文中，在@body参数的内容之后。当值为值 1时，结果将作为附件返回。仅当指定了@query时，此参数才适用。

[ @query_attachment_filename = ] N'query_attachment_filename'

指定查询结果集附件使用的文件名。 @query_attachment_filename的类型为 nvarchar（255），默认值为 NULL. 当@attach_query_result_as_file为 0/> 时，将忽略此参数。当@attach_query_result_as_file为1此参数NULL时，数据库邮件创建任意文件名。

[ @query_result_header = ] query_result_header

指定查询结果是否包含列标题。 query_result_header值的类型为位。当值为值 1时，查询结果包含列标题。如果值为值 0，则查询结果不包含列标题。此参数默认为 1. 仅当指定了@query时，此参数才适用。

将@query_result_header0设置为以下错误，并将@query_no_truncate设置为1：

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

[ @query_result_width = ] query_result_width

用于设置查询结果格式的行宽（以字符为单位）。 @query_result_width的类型为 int，默认值为 256. 提供的值必须介于 10 和 32767。仅当指定了@query时，此参数才适用。

[ @query_result_separator = ] 'query_result_separator'

用于分隔查询输出中的各列的字符。分隔符的类型为 char（1）。 默认值为 ' ' （空格）。

[ @exclude_query_output = ] exclude_query_output

指定是否使用电子邮件返回查询执行的输出。 @exclude_query_output为位，默认值为 0. 当此参数为 0此参数时，存储过程的执行 sp_send_dbmail 将输出在控制台上作为查询执行结果返回的消息。如果此参数为 1此参数，则存储过程的执行 sp_send_dbmail 不会在控制台上打印任何查询执行消息。

[ @append_query_error = ] append_query_error

指定当错误从@query参数中指定的查询返回时是否发送电子邮件。 @append_query_error为位，默认值为 0. 如果此参数为1此参数，数据库邮件发送电子邮件，并在电子邮件正文中包含查询错误消息。如果此参数为0此参数，则数据库邮件不会发送电子邮件，并且sp_send_dbmail以返回代码1结尾，表示失败。

[ @query_no_truncate = ] query_no_truncate

指定是否使用选项执行查询，以避免截断大型可变长度数据类型（varchar（max）、nvarchar（max）、varbinary（max）、xml、text、ntext、image 和用户定义的数据类型）。设置后，查询结果不包含列标题。 @query_no_truncate值的类型为位。如果未指定该值 0 ，查询中的列将截断为 256 个字符。如果值为值 1，则查询中的列不会被截断。此参数默认为 0.

注意

当与大量数据一起使用时， @query_no_truncate 选项会消耗其他资源，并且可能会降低服务器性能。

[ @query_result_no_padding = ] query_result_no_padding

类型为位。默认为 0。设置为 1/> 时，不会填充查询结果，可能会减小文件大小。如果设置为@query_result_no_padding1并设置@query_result_width参数，@query_result_no_padding参数将覆盖@query_result_width参数。

在这种情况下，不会发生错误。

将@query_result_no_padding1设置为@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.

如果将@query_result_no_padding1设置为并设置@query_no_truncate参数，则会引发错误。

[ @mailitem_id = ] mailitem_id [ OUTPUT ]

可选的输出参数返回 mailitem_id 消息。 @mailitem_id 的类型 为 int。

返回代码值

表示成功的返回代码 0 。任何其他值都意味着失败。失败的语句的错误代码存储在变量中 @@ERROR 。

结果集

成功时，返回消息“邮件已排队”。

注解

使用前，必须使用数据库邮件数据库邮件配置向导sp_configure或 .

sysmail_stop_sp通过停止外部程序使用的 Service Broker 对象来停止数据库邮件。 sp_send_dbmail在使用停止sysmail_stop_sp数据库邮件时仍接受邮件。若要开始数据库邮件，请使用 sysmail_start_sp。

如果未指定@profile，sp_send_dbmail请使用默认配置文件。如果发送电子邮件的用户具有默认专用配置文件，则数据库邮件使用该配置文件。如果用户没有默认的专用配置文件， sp_send_dbmail 请使用默认的公共配置文件。如果用户没有默认的专用配置文件，并且没有默认的公共配置文件， sp_send_dbmail 则返回错误。

sp_send_dbmail 不支持没有内容的电子邮件。若要发送电子邮件，必须至少指定@body、@query、@file_attachments或@subject之一。否则， sp_send_dbmail 返回错误。

数据库邮件使用当前用户的 Windows 安全上下文控制对文件的访问。因此，使用 SQL Server 身份验证进行身份验证的用户无法使用@file_attachments附加文件。 Windows 不允许 SQL Server 将凭据从远程计算机提供给另一台远程计算机。因此，数据库邮件在运行 SQL Server 的计算机以外的计算机中运行命令的情况下，可能无法从网络共享附加文件。

如果同时指定了@query和@file_attachments，并且找不到文件，则仍会执行查询，但不会发送电子邮件。

指定查询后，结果集的格式被设置为内联文本。使用十六进制格式发送结果中的二进制数据。

参数 @recipients、 @copy_recipients和 @blind_copy_recipients 是以分号分隔的电子邮件地址列表。必须至少提供其中一个参数，或 sp_send_dbmail 返回错误。

在没有事务上下文的情况下执行sp_send_dbmail时，数据库邮件启动并提交隐式事务。从现有事务中执行sp_send_dbmail时，数据库邮件依赖于用户提交或回滚任何更改。它不会启动内部事务。

权限

对数据库中 DatabaseMailUser 数据库角色msdb的所有成员执行默认权限sp_send_dbmail。 但是，当发送消息的用户无权使用请求的配置文件时， sp_send_dbmail 将返回错误，并且不发送消息。

示例

A. 发送电子邮件

本示例使用电子邮件地址 myfriend@adventure-works.com向朋友发送电子邮件。该邮件的主题为 Automated Success Message。邮件正文包含一句话 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. 发送包含查询结果的电子邮件

本示例使用电子邮件地址 yourfriend@adventure-works.com向朋友发送电子邮件。邮件具有主题 Work Order Count，并执行一个查询，该查询显示 2022 年 4 月 30 日之后不到两天的工单 DueDate 数。数据库邮件将该结果附加为文本文件。

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 发送 HTML 电子邮件

本示例使用电子邮件地址 yourfriend@adventure-works.com向朋友发送电子邮件。邮件包含主题 Work Order List，并包含一个 HTML 文档，该文档显示工作订单，在 DueDate 2022 年 4 月 30 日之后不到两天。数据库邮件使用 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';

通过