sp_send_dbmail (Transact-SQL)
適用対象: 
SQL Server Azure SQL Managed Instance
指定した受信者に電子メール メッセージを送信します。 メッセージには、クエリ結果セット、添付ファイル、またはその両方が含まれる場合があります。 メールがデータベース メール キューに正常に配置されると、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 = ] 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は、既存のデータベース メール プロファイルの名前である必要があります。 @profile_nameが指定されていない場合、sp_send_dbmailは現在のユーザーの既定のプライベート プロファイルを使用します。 ユーザーが既定のプライベート プロファイルを持っていない場合、 sp_send_dbmail は msdb データベースの既定のパブリック プロファイルを使用します。 ユーザーに既定のプライベート プロファイルがなく、データベースの既定のパブリック プロファイルがない場合は、 @profile_name を指定する必要があります。
[ @recipients = ] 'recipients'
メッセージを送信する電子メール アドレスのセミコロン区切りのリスト。 受信者リストの種類は varchar(max)です。 このパラメーターは省略可能ですが、少なくとも 1 つの @recipients、 @copy_recipients、または @blind_copy_recipients を指定するか、 sp_send_dbmail エラーを返す必要があります。
[ @copy_recipients = ] 'copy_recipients'
メッセージのカーボン コピー先の電子メール アドレスのセミコロン区切りのリスト。 コピー先リストは、 varchar(max)型です。 このパラメーターは省略可能ですが、少なくとも 1 つの @recipients、 @copy_recipients、または @blind_copy_recipients を指定するか、 sp_send_dbmail エラーを返す必要があります。
[ @blind_copy_recipients = ] 'blind_copy_recipients'
メッセージのコピー先のブラインド カーボンの電子メール アドレスのセミコロン区切りのリスト。 ブラインド コピー受信者リストは、 varchar(max)型です。 このパラメーターは省略可能ですが、少なくとも 1 つの @recipients、 @copy_recipients、または @blind_copy_recipients を指定するか、 sp_send_dbmail エラーを返す必要があります。
[ @from_address = ] 'from_address'
電子メール メッセージの "from address" の値。 これは、メール プロファイルの設定をオーバーライドするために使用される省略可能なパラメーターです。 このパラメーターの型は varchar(max)です。 オーバーライドが許可されるかどうかは、SMTP のセキュリティ設定によって決まります。 パラメーターが指定されていない場合、既定値は NULL です。
[ @reply_to = ] 'reply_to'
電子メール メッセージの "アドレスへの返信" の値。 有効な値として受け取る電子メール アドレスは 1 つだけです。 これは、メール プロファイルの設定をオーバーライドするために使用される省略可能なパラメーターです。 このパラメーターの型は 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)です。 パラメーターには、次のいずれかの値が含まれる場合があります。
LowNormal(既定)High
[ @sensitivity = ] 'センシティビティ'
メッセージの秘密度。 パラメーターの型は varchar(12)です。 パラメーターには、次のいずれかの値が含まれる場合があります。
Normal(既定)PersonalPrivateConfidential
[ @file_attachments = ] N'file_attachments'
電子メール メッセージに添付するファイル名のセミコロン区切りのリスト。 リスト内のファイルは絶対パスとして指定する必要があります。 添付ファイルの一覧の種類は nvarchar(max)です。 既定では、データベース メールの添付ファイルは 1 ファイルにつき 1 MB に制限されます。
重要
このパラメーターは、ローカル ファイル システムにアクセスできないため、Azure SQL Managed Instance では使用できません。
[ @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 ID、および Microsoft Entra ID はクエリを実行できますが、Azure SQL Managed Instance の偽装と 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_fileが0されている場合、このパラメーターは無視されます。 @attach_query_result_as_fileが1され、このパラメーターがNULLされると、データベース メールは任意のファイル名を作成します。
[ @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 です。 指定する値は、 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すると、データベース メールは電子メール メッセージを送信し、電子メール メッセージの本文にクエリ エラー メッセージを含めます。 このパラメーターが0されると、データベース メールは電子メール メッセージを送信せず、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 です。
Note
大量のデータと共に使用すると、 @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のパラメーターを指定すると、次のエラーが発生する可能性があります。
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 変数に格納されます。
結果セット
成功すると、"メールがキューに登録されました。" というメッセージが返されます。
解説
データベース メールを使用する前に、データベース メール構成ウィザードまたはsp_configureを使用して有効にする必要があります。
sysmail_stop_spは、外部プログラムが使用する Service Broker オブジェクトを停止することによって、データベース メールを停止します。 sp_send_dbmailは、sysmail_stop_spを使用してデータベース メールが停止した場合でもメールを受け入れます。 データベース メールを開始するには、sysmail_start_spを使用します。
@profileが指定されていない場合、sp_send_dbmailは既定のプロファイルを使用します。 電子メール メッセージを送信するユーザーに既定のプライベート プロファイルがある場合、データベース メールではそのプロファイルが使用されます。 ユーザーに既定のプライベート プロファイルがない場合、 sp_send_dbmail は既定のパブリック プロファイルを使用します。 ユーザーの既定のプライベート プロファイルがなく、既定のパブリック プロファイルがない場合、 sp_send_dbmail はエラーを返します。
sp_send_dbmail では、コンテンツのない電子メール メッセージはサポートされません。 電子メール メッセージを送信するには、少なくとも 1 つの @body、 @query、 @file_attachments、または @subjectを指定する必要があります。 それ以外の場合、 sp_send_dbmail はエラーを返します。
データベース メールは、現在のユーザーの Microsoft Windows セキュリティ コンテキストを使用して、ファイルへのアクセスを制御します。 そのため、SQL Server 認証で認証されたユーザーは、 @file_attachmentsを使用してファイルを添付できません。 Windows では、SQL Server がリモート コンピューターから別のリモート コンピューターに資格情報を提供することはできません。 そのため、SQL Server が実行されているコンピューター以外のコンピューターからコマンドを実行した場合、データベース メールはネットワーク共有からファイルをアタッチできない可能性があります。
@queryと@file_attachmentsの両方が指定されていて、ファイルが見つからない場合、クエリは引き続き実行されますが、電子メールは送信されません。
クエリを指定すると、結果セットはインライン テキストとして書式設定されます。 結果セットにあるバイナリ データは 16 進数形式で送信されます。
パラメーター @recipients、 @copy_recipients、および @blind_copy_recipients は、電子メール アドレスのセミコロン区切りのリストです。 これらのパラメーターのうち少なくとも 1 つを指定するか、エラー sp_send_dbmail 返す必要があります。
トランザクション コンテキストなしでsp_send_dbmailを実行すると、データベース メールが開始され、暗黙的なトランザクションがコミットされます。 既存のトランザクション内からsp_send_dbmailを実行する場合、データベース メールはユーザーに依存して変更をコミットまたはロールバックします。 内部トランザクションは開始されません。
アクセス許可
msdb データベースの DatabaseMailUser データベース ロールのすべてのメンバーに対する既定の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 日から 2 日以内に DueDate された作業指示書の数を示すクエリが実行されます。 データベース メール結果をテキスト ファイルとして添付します。
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があり、2022 年 4 月 30 日から 2 日以内に DueDate の作業指示書を示す HTML ドキュメントが含まれています。 データベース メールでは、このメッセージが 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';
関連するコンテンツ
フィードバック
以下は間もなく提供いたします。2024 年を通じて、コンテンツのフィードバック メカニズムとして GitHub の issue を段階的に廃止し、新しいフィードバック システムに置き換えます。 詳細については、「https://aka.ms/ContentUserFeedback」を参照してください。
フィードバックの送信と表示