共用方式為

  • 發行項

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。如需詳細資訊，請參閱＜Database Mail 組態精靈＞。

  • [ @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 為 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 參數，則會引發錯誤。

  • [ @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。使用 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 = 'AdventureWorks 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 = 'AdventureWorks Administrator',
    @recipients = 'danw@Adventure-Works.com',
    @query = 'SELECT COUNT(*) FROM AdventureWorks.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' ;

變更記錄

更新的內容

新參數 @from_address 和 @reply_to 的相關資訊已加入至「語法」和「引數」這幾節。