共用方式為


sp_send_dbmail (Transact-SQL)

適用於:SQL Server Azure SQL 受控執行個體

將電子郵件訊息傳送給指定的收件者。 訊息可能包含查詢結果集、檔案附件或兩者。 成功將郵件放置在 Database Mail 佇列中時, sp_send_dbmailmailitem_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 = ] N'subject' ]
    [ , [ @body = ] N'body' ]
    [ , [ @body_format = ] 'body_format' ]
    [ , [ @importance = ] 'importance' ]
    [ , [ @sensitivity = ] 'sensitivity' ]
    [ , [ @file_attachments = ] N'attachment [ ; ...n ]' ]
    [ , [ @query = ] N'query' ]
    [ , [ @execute_query_database = ] 'execute_query_database' ]
    [ , [ @attach_query_result_as_file = ] attach_query_result_as_file ]
    [ , [ @query_attachment_filename = ] N'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'

電子郵件訊息的「回復位址」值。 它只接受一個電子郵件地址作為有效值。 這是選擇性參數,用來覆寫郵件配置檔中的設定。 此參數的類型為 varchar(max)。 SMTP 安全性設定會判斷是否接受這些覆寫。 如果未指定任何參數,則預設值為 NULL

[ @subject = ] N'subject'

電子郵件訊息的主旨。 主旨的類型為 nvarchar(255)。 如果未指定主旨,則預設值為 「SQL Server 訊息」。

[ @body = ] N'body'

電子郵件訊息的本文。 訊息本文的類型 為 nvarchar(max),預設值為 NULL

[ @body_format = ] 'body_format'

訊息本文的格式。 參數的類型為 varchar(20),預設值為 NULL。 指定時,傳出訊息的標頭會設定為表示訊息本文具有指定的格式。 參數可能包含下列其中一個值:

  • TEXT (預設值)
  • HTML

[ @importance = ] 'importance'

訊息的重要性。 參數的類型為 varchar(6)。 參數可能包含下列其中一個值:

  • Low
  • Normal (預設值)
  • High

[ @sensitivity = ] 'sensitivity'

訊息的敏感度。 參數的類型為 varchar(12)。 參數可能包含下列其中一個值:

  • Normal (預設值)
  • Personal
  • Private
  • Confidential

[ @file_attachments = ] N'file_attachments'

要附加至電子郵件訊息之檔名的分號分隔清單。 清單中的檔案必須指定為絕對路徑。 附件清單的類型 為 nvarchar(max)。 根據預設,Database Mail 會將檔案附件限製為每個檔案 1 MB。

重要

此參數無法在 Azure SQL 受控執行個體 中使用,因為它無法存取本機文件系統。

[ @query = ] N'query'

要執行的查詢。 查詢的結果可以附加為檔案,或包含在電子郵件訊息的本文中。 此查詢的類型 為 nvarchar(max),而且可以包含任何有效的 Transact-SQL 語句。 查詢會在個別會話中執行,因此呼叫的腳本 sp_send_dbmail 中的局部變數無法供查詢使用。

當您使用 @query 參數時,執行的 sp_send_dbmail 主體必須以個人身分連線,而不是作為群組的一部分,無論是Microsoft Entra ID(先前稱為 Azure Active Directory)還是 Windows Active Directory 群組。 SQL Server 登入、Windows 身分識別和Microsoft Entra 身分識別可以執行查詢,但群組成員因為 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 = ] N'query_attachment_filename'

指定要用於查詢附件結果集的檔名。 @query_attachment_filename 類型為 nvarchar(255),預設值為 NULL。 當 @attach_query_result_as_file0,會忽略此參數。 當@attach_query_result_as_file1 且此參數為 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設定為 時,可能會發生下列錯誤:

Msg 22050, Level 16, State 1, Line 12: Failed to initialize sqlcmd library with error number -2147024809.

[ @query_result_width = ] query_result_width

要用來格式化查詢結果的行寬,以字元為單位。 @query_result_width的類型為 int,預設值為 256。 所提供的值必須介於和 32767之間10。 只有在指定@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)xmltextntextimage 和使用者定義數據類型。 設定時,查詢結果不會包含數據行標頭。 @query_no_truncate值的類型為 bit。 當值未 0 指定時,查詢中的數據行會截斷為 256 個字元。 當值為 1時,不會截斷查詢中的數據行。 此參數預設為 0

注意

搭配大量數據使用時, @query_no_truncate 選項會耗用額外的資源,而且可能會降低伺服器效能。

[ @query_result_no_padding = ] query_result_no_padding

此類型為 bit。 預設值為 0。 當您將 設定為 1時,查詢結果不會填補,可能會減少檔案大小。 如果您將 設定為 1 並設定 @query_result_no_padding @query_result_width 參數,@query_result_no_padding參數會覆寫 @query_result_width 參數。

在此情況下,不會發生任何錯誤。

將 @query_result_no_padding 設定1 並提供 @query_no_truncate 的參數時,可能會發生下列錯誤:

Msg 22050, Level 16, State 1, Line 0: Failed to execute the query because the @query_result_no_append and @query_no_truncate options are mutually exclusive.

如果您將@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_spDatabase Mail 時仍接受郵件。 若要啟動 Database Mail 請使用 sysmail_start_sp

未指定@profilesp_send_dbmail請使用預設配置檔。 如果傳送電子郵件訊息的使用者具有預設的私人配置檔,Database Mail 會使用該配置檔。 如果使用者沒有預設的私人配置檔, sp_send_dbmail 請使用預設的公用配置檔。 如果使用者沒有預設的私人配置檔,也沒有預設的公用配置檔, sp_send_dbmail 則傳回錯誤。

sp_send_dbmail 不支援沒有內容的電子郵件訊息。 若要傳送電子郵件訊息,您必須至少指定其中一個@body、@query、@file_attachments或@subject。 否則, sp_send_dbmail 會傳回錯誤。

Database Mail 使用目前使用者的 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 會依賴使用者認可或回復任何變更。 它不會啟動內部交易。

權限

針對資料庫中 DatabaseMailUser 資料庫角色msdb的所有成員執行預設許可權sp_send_dbmail 不過,當傳送訊息的使用者沒有許可權使用要求的配置檔時, 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,並執行查詢,此查詢會顯示在 2022 年 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 AdventureWorks2022.Production.WorkOrder
                  WHERE DueDate > ''2022-04-30''
                  AND  DATEDIFF(dd, ''2022-04-30'', DueDate) < 2',
    @subject = 'Work Order Count',
    @attach_query_result_as_file = 1;

C. 傳送 HTML 電子郵件訊息

此範例會使用電子郵件位址 yourfriend@adventure-works.com,將電子郵件訊息傳送給您的朋友。 郵件的主旨 Work Order List為 ,並包含 HTML 檔,其中顯示工作訂單 DueDate 在 2022 年 4 月 30 日之後不到兩天。 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
            INNER JOIN AdventureWorks.Production.Product AS p
                ON wo.ProductID = p.ProductID
            WHERE DueDate > '2022-04-30'
                AND DATEDIFF(dd, '2022-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';