向指定的收件人发送邮件和查询结果集附件。

语法

xp_sendmail {[@recipients =] 'recipients [;...n]'}

    [,[@message =] 'message']

    [,[@query =] 'query']

    [,[@attachments =] 'attachments [;...n]']

    [,[@copy_recipients =] 'copy_recipients [;...n]'

    [,[@blind_copy_recipients =] 'blind_copy_recipients [;...n]'

    [,[@subject =] 'subject']

    [,[@type =] 'type']

    [,[@attach_results =] 'attach_value']

    [,[@no_output =] 'output_value']

    [,[@no_header =] 'header_value']

    [,[@width =] width]

    [ , [ @separator = ] 'separator' ]

    [,[@echo_error =] 'echo_value']

    [ , [ @set_user = ] 'user' ]

    [,[@dbuse =] 'database']

参数

[@recipients =] 'recipients [;...n]'

是以分号分隔的邮件收件人列表。

n

是表示可以指定多个 recipient、copy_recipient 或 blind_copy_recipient 的占位符。

[@message =] 'message'

是要发送的邮件。message 最大可达 8.000 个字节。

[@query =] 'query'

是有效的 Microsoft® SQL Server™ 查询，其结果将通过邮件送出。xp_sendmail 对 query 参数使用绑定连接。SQL 邮件建立的 query 连接不会被发出 xp_sendmail 请求的客户端所控制的锁阻塞。这使 xp_sendmail 更易于在触发器中使用。但是，query 语句不能引用仅在触发器中可用的逻辑 inserted 表和 deleted 表。query 最大可达 8,000 个字节。

[@attachments =] 'attachments [;...n]'

是以分号分隔的附加到邮件上的文件列表。

[@copy_recipients =] 'copy_recipients [;...n]'

是以分号分隔的列表，标识邮件复本收件人（抄送人）。

[@blind_copy_recipients =] 'blind_copy_recipients [;...n]'

是可选的以分号分隔的列表，标识邮件密件复本收件人（密件抄送人）。

[@subject =] 'subject'

是指定邮件主题的可选参数。如果未指定 subject，则默认值为"SQL Server 消息"。

[@type =] 'type'

是基于以下 MAPI 邮件定义的输入邮件类型：

IP[M | C].Vendorname.subclass

如果 type 为 NULL，则以 IPM 打头的邮件类型出现在邮件客户端的收件箱中，并由 xp_findnextmsg 查找或阅读。以 IPC 打头的邮件类型不出现在邮件客户程序的收件箱中，并且必须设置 type 参数才能查找或阅读。默认设置为 NULL。

有关使用自定义邮件类型的更多信息，请参见独立提供的《Microsoft Windows NT Resource Kit》或《Microsoft Mail Technical Reference》。

[@attach_results =] 'attach_value'

是可选参数，指定查询结果集应作为邮件中的附件文件发送，而不是追加到邮件中发送。如果 attachments 不为 NULL，并且 attach_results 为 true，则 attachments 中的第一个文件名将作为结果集的文件名。如果 attachments 为 NULL，则生成带 .txt 扩展名的文件名。默认值为 FALSE，这意味着结果集将追加到邮件中。

[@no_output =] 'output_value'

是可选参数，用来发送邮件但不向发送邮件的客户端会话返回任何输出。默认值为 FALSE，这意味着 SQL Server 客户端会话将接收输出。

[@no_header =] 'header_value'

是可选参数，表示通过邮件发送查询结果，但不随查询结果发送列标题信息。默认值为 FALSE，即列标题信息随查询结果一起发送。

[@width =] width

是可选参数，设置查询的输出文本行宽。此参数与 isql 实用工具中的 /w 参数相同。对于产生长输出行的查询，应结合使用 attach_results 与 width 以发送行中无换行符的输出。默认宽度为 80 个字符。

[@separator =] 'separator'

是结果集中每列的列分隔符字符串。默认情况，列分隔符为空格。使用列分隔符可以使访问电子表格和其它应用程序中的结果集更容易。例如，结合使用 attach_results 与 separator 以发送用逗号分隔值的文件。

[@echo_error =] 'echo_value'

值为 true 时，SQL 邮件将捕获运行查询时遇到的任何服务器消息或 DB-Library 错误，并将其追加到邮件中而不是写入错误日志。同时也将返回行/受影响行的计数追加到邮件中。

说明  echo_error 为 true 时，即使出现 DB-Library 错误或消息，或查询没有返回结果，只要邮件成功发送，xp_sendmail 就返回状态 0（成功）。

[@set_user =] 'user'

是应在其中运行查询的安全上下文。如果没有指定 user，安全上下文默认为执行 xp_sendmail 的用户的安全上下文。

[@dbuse =] 'database'

是应在其中运行查询的数据库上下文。默认值为 NULL，这意味着将用户置于默认数据库中。

返回代码值

0（成功）或 1（失败）

结果集

xp_sendmail 返回下列消息：

Mail sent.

注释

必须在执行 xp_sendmail 前启动 SQL 邮件会话。会话可以自动启动，也可以使用 xp_startmail 启动。有关自动设置 SQL 邮件会话的更多信息，请参见配置邮件配置文件。一个 SQL 邮件会话支持 SQL Server 上的所有用户，但每次只有一个用户可以发送邮件。其他发送邮件的用户自动排队等候，直到第一个用户的邮件发送出去。

如果指定 query，则 xp_sendmail 作为客户端登录到 SQL Server，并执行指定的查询。SQL 邮件建立与 SQL Server 之间的单独的连接；它不与发出 xp_sendmail 的原始客户端连接共享同一连接。

说明  发出 xp_sendmail 的客户端连接所控制的锁会阻塞 query。例如，如果要在事务中更新表，并且为更新创建了触发器，而该触发器试图选择的更新行信息与 query 参数所选择的相同，则 SQL 邮件连接将被初始客户端连接所控制的行排它锁阻塞。

xp_sendmail 在 SQL Server 的安全上下文（默认为本地管理员帐户）中运行。有效 xp_sendmail 用户可以在管理员安全上下文中访问邮件的附件文件。如果非系统管理员用户必须访问 xp_sendmail，而您希望阻止对附件文件的不安全访问，则系统管理员可以创建一个存储过程，该过程调用 xp_sendmail 并提供所需的功能，但不表现 attachments 参数。此存储过程必须在 master 数据库中定义。然后系统管理员可向必要的用户授予该存储过程的执行权限，但不授予基础 xp_sendmail 过程的权限。

xp_sendmail 向指定收件人发送邮件、查询结果集或附件，并对 query 参数使用绑定连接。SQL 邮件建立的 query 连接不会被发出 xp_sendmail 请求的客户端所控制的锁阻塞。这使 xp_sendmail 更易于在触发器中使用。但是，query 语句不能引用仅在触发器中可用的逻辑 inserted 和 deleted 表。

说明  当邮局和通讯簿位于 MSSQLServer 服务因无足够权限而无法访问的文件共享位置时，试图执行 xp_sendmail 将导致违规访问。

有关使用存储过程调用 xp_sendmail 的更多信息，请参见如何使用 SQL 邮件(Transact-SQL)。

权限

xp_sendmail 的执行权限默认授予 master 数据库中的 db_owner 固定数据库角色成员以及 sysadmin 固定服务器角色成员，但可以授予其他用户。

示例

A. 使用不带变量的 xp_sendmail

下例向用户 Robert King（电子邮件地址是 robertk）发送邮件，告知该用户 master 数据库已满。

EXEC xp_sendmail 'robertk', 'The master database is full.'

B. 使用带变量的 xp_sendmail

下例向用户 Robert King 和 Laura Callahan（电子邮件地址是 laurac）发送邮件，并将复本发送给 Anne Dodsworth（电子邮件地址是 anned）和 Michael Suyama（电子邮件地址是 michaels）。下例还指定了邮件的主题行。

EXEC xp_sendmail @recipients = 'robertk;laurac', 
   @message = 'The master database is full.',
   @copy_recipients = 'anned;michaels',
   @subject = 'Master Database Status'

C. 发送结果

下例将 sp_configure 的结果发送给 Robert King。

EXEC xp_sendmail 'robertk', @query = 'sp_configure'

D. 将结果作为附件文件发送

下例将查询 SELECT * FROM INFORMATION_SCHEMA.TABLES 的结果作为文本文件附件发送给 Robert King。下例包含邮件的主题行以及将在附件之前出现的邮件正文。@width 参数用于防止在输出行中换行。

EXEC xp_sendmail @recipients = 'robertk', 
   @query = 'SELECT * FROM INFORMATION_SCHEMA.TABLES',
   @subject = 'SQL Server Report',
   @message = 'The contents of INFORMATION_SCHEMA.TABLES:',
   @attach_results = 'TRUE', @width = 250

E. 发送大于 7,990 个字符的邮件

下例显示如何发送大于 7,990 个字符的邮件。由于 message 受 varchar 长度的限制（这样每行开销较小，像所有存储过程参数一样），下例将长消息写入由单个文本列组成的全局临时表中。然后使用 @query 参数通过邮件发送该临时表的内容。

CREATE TABLE ##texttab (c1 text)
INSERT ##texttab values ('Put your long message here.')
DECLARE @cmd varchar(56)
SET @cmd = 'SELECT c1 FROM ##texttab'
EXEC master.dbo.xp_sendmail 'robertk', 
   @query = @cmd, @no_header= 'TRUE'
DROP TABLE ##texttab