sp_send_dbmail (Transact-SQL)

适用于: SQL Server Azure SQL 托管实例

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

Transact-SQL 语法约定

语法

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_namesp_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_file1此参数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. 提供的值必须介于 1032767。 仅当指定了@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)xmltextntextimage 和用户定义的数据类型)。 设置后,查询结果不包含列标题。 @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

如果未指定@profilesp_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';