sp_send_dbmail (Transact-SQL)
適用於：
SQL ServerAzure SQL 受控執行個體
將電子郵件訊息傳送給指定的收件者。 訊息可能包含查詢結果集、檔案附件，或兩者皆有。 成功將郵件放在Database Mail佇列中時，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 = ] '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' 這是電子郵件訊息的「寄件者位址」值。 這是選擇性參數，用來覆寫郵件設定檔中的設定。 此參數的類型為 Varchar (MAX) 。 SMTP 安全性設定會決定是否要接受這些覆寫。 如果沒有指定參數，預設值為 NULL。
[ @reply_to = ] 'reply_to' 這是電子郵件訊息的「回復位址」值。 它只接受一個電子郵件地址做為有效的值。 這是選擇性參數，用來覆寫郵件設定檔中的設定。 此參數的類型為 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) 。 參數可包含下列各值之一：
低
正常
高
預設值是 Normal。
[ @sensitivity = ] 'sensitivity' 這是訊息的敏感度。 參數的類型為 Varchar (12) 。 參數可包含下列各值之一：
正常
個人
私人
機密
預設值是 Normal。
[ @file_attachments = ] 'file_attachments' 這是要附加至電子郵件訊息的以分號分隔的檔案名清單。 清單中的檔案必須指定為絕對路徑。 附件清單的類型為 Nvarchar (max) 。 根據預設，Database Mail 會將檔案附件限制為每個檔案 1 MB。
重要
Azure SQL 受控執行個體中無法使用此參數，因為它無法存取本機檔案系統。
[ @query = ] 'query' 這是要執行的查詢。 查詢的結果可以附加成一個檔案，也可以包含在電子郵件訊息的主體中。 查詢的類型為 Nvarchar (max) ，而且可以包含任何有效的 Transact-SQL 語句。 請注意，查詢是在個別的會話中執行，因此呼叫 sp_send_dbmail 腳本中的區域變數不適用於查詢。
注意
使用 @query 參數時，執行 sp_send_dbmail 的使用者必須是 SQL 登入，或直接對應至 Azure AD 或 AD 的主體 (登入) 。 如果使用者是 Azure AD 群組或 AD 群組的成員，將無法執行查詢。 這是因為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 的類型為 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_header 設為 0 並將 @query_no_truncate 設為 1 時，可能會發生下列錯誤：
訊息 22050，層級 16，狀態 1，行 12：無法初始化 sqlcmd 程式庫，錯誤號碼為 -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 為 bit，預設值為 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 時，可能會發生下列錯誤：
訊息 22050、層級 16、狀態 1、第 0 行：無法執行查詢，因為@query_result_no_append和@query_no_truncate選項互斥。
如果您將 @query_result_no_padding 設定為 1，而且設定了 @query_no_truncate 參數，就會引發錯誤。
[ @mailitem_id = ] mailitem_id [ OUTPUT ] 選擇性輸出參數會傳回訊息 的mailitem_id 。 mailitem_id的類型為int。
傳回碼值
傳回碼為 0 表示成功。 其他任何值都表示失敗。 失敗語句的錯誤碼會儲存在 @@ERROR 變數中。
結果集
成功時，傳回「郵件已列入佇列」訊息。
備註
使用之前，必須使用 Database Mail 組態精靈或sp_configure來啟用Database Mail。
sysmail_stop_sp停止外部程式所使用的 Service Broker 物件，以停止Database Mail。 sp_send_dbmail在使用 sysmail_stop_sp 停止Database Mail時仍接受郵件。 若要開始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將認證從遠端電腦提供給另一部遠端電腦。 因此，Database Mail在命令從執行SQL Server的電腦以外的電腦執行時，可能無法從網路共用連結檔案。
如果 同時指定@query 和 @file_attachments ，而且找不到檔案，則仍會執行查詢，但不會傳送電子郵件。
當指定查詢時，結果集會格式化為內嵌文字。 結果中的二進位資料會以十六進位格式傳送。
參數 @recipients、 @copy_recipients和 @blind_copy_recipients 都是以分號分隔的電子郵件地址清單。 至少必須提供其中一個參數，或 sp_send_dbmail 傳回錯誤。
在沒有交易內容的情況下執行sp_send_dbmail時，Database Mail啟動並認可隱含交易。 從現有交易內執行sp_send_dbmail時，Database Mail依賴使用者認可或復原任何變更。 它並不會啟動內部交易。
權限
執行sp_send_dbmail的許可權預設為msdb資料庫中DatabaseMailUser資料庫角色的所有成員。 不過，當傳送訊息的使用者沒有許可權使用要求的設定檔時， 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，且會執行查詢來顯示在 2004 年 4 月 30 日之後 DueDate 小於兩天的工作訂單數目。 Database Mail 會將結果附加為一個文字檔。
EXEC msdb.dbo.sp_send_dbmail
@profile_name = 'Adventure Works Administrator',
@recipients = 'yourfriend@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 電子郵件訊息
本範例會使用電子郵件地址 yourfriend@Adventure-Works.com ，將電子郵件訊息傳送給您的朋友。 訊息的主旨是 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='yourfriend@Adventure-Works.com',
@subject = 'Work Order List',
@body = @tableHTML,
@body_format = 'HTML' ;
另請參閱
Database Mail
Database Mail 組態物件
Database Mail 預存程序 (Transact-SQL)
sp_addrolemember (Transact-SQL)