sp_send_dbmail (Transact-SQL)

將電子郵件訊息傳送給指定的收件者。 訊息可能包含查詢結果集、檔案附件，或兩者皆有。 當郵件順利放在 Database Mail 佇列時，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 = ] '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 必須是現有 Database Mail 設定檔的名稱。 當沒有指定 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)。 根據預設，Database Mail 會將檔案附件限制為每個檔案 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 時，Database Mail 會建立任意檔案名稱。
[ @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 是位元，預設值為 0。 當此參數是 0 時，執行 sp_send_dbmail 預存程序不會在主控台上列印當做查詢執行結果傳回的訊息。 當此參數是 1 時，sp_send_dbmail 預存程序的執行不會在控制台上列印任何查詢執行訊息。
[ @append_query_error= ] append_query_error
指定在 @query 引數中指定的查詢傳回錯誤時，是否傳送電子郵件。 append_query_error 是 bit，預設值是 0。 當這個參數是 1 時，Database Mail 會傳送電子郵件，且會在電子郵件的主體中包含查詢錯誤訊息。 當這個參數是 0 時，Database Mail 不會傳送電子郵件訊息，且 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 變數中。
結果集
成功時，傳回「郵件已列入佇列」訊息。
備註
使用之前，您必須利用 Database Mail 組態精靈或 sp_configure 來啟用 Database Mail。
sysmail_stop_sp 會停止外部程式使用的 Service Broker 物件來停止 Database Mail。 使用 sysmail_stop_sp 停止 Database Mail 時，sp_send_dbmail 仍接受郵件。 若要啟動 Database Mail，請使用 sysmail_start_sp。
當未指定 @profile 時，sp_send_dbmail 會使用預設的設定檔。 如果傳送電子郵件訊息的使用者有預設私人設定檔，Database Mail 會使用這個設定檔。 如果使用者沒有預設私人設定檔，sp_send_dbmail 會使用預設公用設定檔。 如果使用者沒有預設私人設定檔，也沒有預設公用設定檔，sp_send_dbmail 就會傳回錯誤。
sp_send_dbmail 不支援沒有內容的電子郵件訊息。 若要傳送電子郵件訊息，您至少必須指定 @body、@query、@file_attachments 或 @subject 其中之一。 否則，sp_send_dbmail 會傳回錯誤。
Database Mail 利用目前使用者的 Microsoft Windows 安全性內容來控制檔案的存取。 因此，以 SQL Server 驗證方法驗證的使用者無法使用 @file_attachments 附加檔案。 Windows 不允許 SQL Server 在遠端電腦之間提供認證。 因此，從執行 SQL Server 的電腦以外的電腦執行命令時，Database Mail 可能無法從網路共用附加檔案。
如果同時指定了 @query 和 @file_attachments，但找不到檔案，仍會執行查詢，但不會傳送電子郵件。
當指定查詢時，結果集會格式化為內嵌文字。 結果中的二進位資料會以十六進位格式傳送。
@recipients、@copy_recipients 和 @blind_copy_recipients 等參數是用分號分隔的電子郵件地址清單。 必須至少提供其中一個參數，否則，sp_send_dbmail 會傳回錯誤。
執行沒有交易內容的 sp_send_dbmail 時，Database Mail 會啟動並認可隱含交易。 從現有交易執行 sp_send_dbmail 時，Database Mail 必須依賴使用者來認可或回復任何變更。 它並不會啟動內部交易。
權限
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，且會執行查詢來顯示在 2004 年 4 月 30 日之後 DueDate 小於兩天的工作訂單數目。 Database Mail 會將結果附加為一個文字檔。
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 文件，其中顯示在 2004 年 4 月 30 日之後 DueDate 小於兩天的工作訂單。 Database Mail 會使用 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' ;



转载于：http://msdn.microsoft.com/zh-tw/library/ms190307.aspx