通过

sp_send_dbmail (Transact-SQL)

  • 项目

向指定收件人发送电子邮件。 该邮件可能包含查询结果集和/或文件附件。 将邮件成功放入数据库邮件队列中后，sp_send_dbmail 将返回邮件的 mailitem_id。 此存储过程位于 msdb 数据库中。

适用范围：SQL Server（SQL Server 2008 到当前版本）。

主题链接图标 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 = ] 'subject' ] 
    [ , [ @body = ] 'body' ] 
    [ , [ @body_format = ] 'body_format' ]
    [ , [ @importance = ] 'importance' ]
    [ , [ @sensitivity = ] 'sensitivity' ]
    [ , [ @file_attachments = ] 'attachment [ ; ...n ]' ]
    [ , [ @query = ] 'query' ]
    [ , [ @execute_query_database = ] 'execute_query_database' ]
    [ , [ @attach_query_result_as_file = ] attach_query_result_as_file ]
    [ , [ @query_attachment_filename = ] 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'
    电子邮件的“from address”的值。 这是一个可选参数，用于覆盖邮件配置文件中的设置。 此参数的类型为 varchar(MAX)。 SMTP 安全设置决定是否接受这些覆盖。 如果未指定参数，则默认值为 NULL。

  • [ @reply_to= ] 'reply_to'
    电子邮件的“reply to address”的值。 它只接受一个电子邮件地址作为有效值。 这是一个可选参数，用于覆盖邮件配置文件中的设置。 此参数的类型为 varchar(MAX)。 SMTP 安全设置决定是否接受这些覆盖。 如果未指定参数，则默认值为 NULL。

  • [ @subject= ] 'subject'
    电子邮件的主题。 主题的类型为 nvarchar(255)。 如果未指定主题，则默认为“SQL Server 消息”。

  • [ @body= ] 'body'
    电子邮件的正文。 邮件正文的类型为 nvarchar(max)，默认值为 NULL。

  • [ @body_format= ] 'body_format'
    邮件正文的格式。 该参数的类型为 varchar(20)，默认值为 NULL。 如果已指定，则待发邮件的标头设置会指示邮件正文具有指定格式。 该参数可能包含下列值之一：

    • TEXT

    • HTML

    默认为 TEXT。

  • [ @importance= ] 'importance'
    邮件的重要性。 该参数的类型为 varchar(6)。 该参数可能包含下列值之一：

    • Low

    • Normal

    • High

    默认值为 Normal。

  • [ @sensitivity= ] 'sensitivity'
    邮件的敏感度。 该参数的类型为 varchar(12)。 该参数可能包含下列值之一：

    • Normal

    • Personal

    • Private

    • Confidential

    默认值为 Normal。

  • [ @file_attachments= ] 'file_attachments'
    电子邮件附件的文件名列表，以分号分隔。 必须使用绝对路径指定列表中的文件。 附件列表的类型为 nvarchar(max)。 默认情况下，数据库邮件会将文件附件限制在每个文件 1 MB 大小。

  • [ @query= ] 'query'
    要执行的查询。 查询结果可以作为文件附加，或包含在电子邮件的正文中。 查询的类型为 nvarchar(max)，并且可以包含任何有效的 Transact-SQL 语句。 请注意，查询在单独的会话中执行，所以调用 sp_send_dbmail 的脚本中的局部变量不可用于查询。

  • [ @execute_query_database= ] 'execute_query_database'
    存储过程在其中运行查询的数据库上下文。 该参数的类型为 sysname，默认为当前数据库。 只有在指定 @query 时，此参数才适用。

  • [ @attach_query_result_as_file= ] attach_query_result_as_file
    指定查询结果集是否作为附件返回。 attach_query_result_as_file 的类型为 bit，默认值为 0。

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

  • [ @query_attachment_filename= ] query_attachment_filename
    指定查询结果集附件使用的文件名。 query_attachment_filename 的类型为 nvarchar(255)，默认值为 NULL。 当 attach_query_result 为 0 时，忽略此参数。 当 attach_query_result 为 1 且此参数为 NULL 时，数据库邮件会创建任意文件名。

  • [ @query_result_header= ] query_result_header
    指定查询结果是否包含列标题。 query_result_header 值的数据类型为 bit。 如果该值为 1，则查询结果包含列标题。 如果该值为 0，则查询结果不包含列标题。 该参数的默认值为 1。 只有在指定 @query 时，此参数才适用。

  • [ @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 的数据类型为 bit，默认值为 0。 当此参数为 0 时，sp_send_dbmail 存储过程的执行将在控制台上打印作为查询执行结果而返回的消息。 当此参数为 1 时，sp_send_dbmail 存储过程的执行不会在控制台上打印任何查询执行消息。

  • [ @append_query_error= ] append_query_error
    指定是否在 @query 参数指定的查询返回错误时发送电子邮件。 append_query_error 的数据类型为 bit，默认值为 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 值的数据类型为 bit。 当该值为 0 或未指定时，查询中的列将截断为 256 个字符。 当该值为 1 时，不截断查询中的列。 此参数的默认值为 0。

    备注

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

  • [ @query_result_no_padding ] @query\_result\_no\_padding
    类型为 bit。 默认值为 0。 设置为 1 时，不填充查询结果，可能减小文件大小。将 @query\_result\_no\_padding 设置为 1 且设置 @query\_result\_width 参数时，@query_result_no_padding 参数覆盖 @query\_result\_width 参数。

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

    如果将 @query\_result\_no\_padding 设置为 1 且设置 @query\_no\_truncate 参数，则将引发错误。

  • [ @mailitem_id= ] mailitem_id [ OUTPUT ]
    可选输出参数将返回消息的 mailitem_id。 mailitem_id 的类型为 int。

返回代码值

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

结果集

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

注释

在使用之前，必须使用数据库邮件配置向导或 sp_configure 启用数据库邮件。

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

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

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

数据库邮件使用当前用户的 Microsoft 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 时，数据库邮件将依赖用户提交或回滚任何更改。 它不会启动内部事务。

权限

默认情况下，msdb 数据库中的 DatabaseMailUser 数据库角色的所有成员对 sp_send_dbmail 都有执行权限。 不过，如果发送邮件的用户不具有使用该请求的配置文件的权限，sp_send_dbmail 会返回错误且不发送该邮件。

示例

A.发送电子邮件

此示例使用电子邮件地址 danw@Adventure-Works.com 向 Dan Wilson 发送电子邮件。 该邮件的主题为 Automated Success Message。 邮件正文包含一句话 'The stored procedure finished successfully'。

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

B.发送包含查询结果的电子邮件

此示例使用电子邮件地址 danw@Adventure-Works.com 向 Dan Wilson 发送电子邮件。 该邮件的主题为 Work Order Count，并执行查询以显示 DueDate 在 2004 年 4 月 30 日后的两日内的工单数。 数据库邮件将该结果附加为文本文件。

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

C.发送 HTML 电子邮件

此示例使用电子邮件地址 danw@Adventure-Works.com 向 Dan Wilson 发送电子邮件。 邮件的主题为 Work Order List，并包含一个 HTML 文档，其中列出了 DueDate 在 2004 年 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
              JOIN AdventureWorks.Production.Product AS p
              ON wo.ProductID = p.ProductID
              WHERE DueDate > '2004-04-30'
                AND DATEDIFF(dd, '2004-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='danw@Adventure-Works.com',
    @subject = 'Work Order List',
    @body = @tableHTML,
    @body_format = 'HTML' ;

请参阅

参考

数据库邮件存储过程 (Transact-SQL)

sp_addrolemember (Transact-SQL)

概念

数据库邮件

数据库邮件配置对象