sp_send_dbmail (Transact-SQL)

[アーティクル]
06/18/2013

指定した受信者に電子メールメッセージを送信します。メッセージには、クエリ結果セットまたは添付ファイル、あるいはその両方を含めることができます。メールがデータベースメールキューに正常に配置されると、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 には、既存のデータベースメールプロファイルの名前を指定する必要があります。 profile_name を指定しないと、sp_send_dbmail では現在のユーザーの既定のプライベートプロファイルが使用されます。ユーザーに既定のプライベートプロファイルがない場合、sp_send_dbmail では msdb データベースの既定のパブリックプロファイルが使用されます。ユーザーに既定のプライベートプロファイルがなく、さらにデータベースに既定のパブリックプロファイルがない場合は、@profile_name を指定する必要があります。
[ @recipients= ] 'recipients'
メッセージの送信先の電子メールアドレスを、セミコロン区切りのリストで指定します。受信者リストのデータ型は varchar(max) です。このパラメーターは省略可能ですが、@recipients、@copy_recipients、または @blind_copy_recipients のうち少なくとも 1 つを指定する必要があります。いずれも指定しない場合、sp_send_dbmail ではエラーが返されます。
[ @copy_recipients= ] 'copy_recipients'
メッセージのカーボンコピーを送信する電子メールアドレスを、セミコロン区切りのリストで指定します。コピーの受信者リストのデータ型は varchar(max) です。このパラメーターは省略可能ですが、@recipients、@copy_recipients、または @blind_copy_recipients のうち少なくとも 1 つを指定する必要があります。いずれも指定しない場合、sp_send_dbmail ではエラーが返されます。
[ @blind_copy_recipients= ] 'blind_copy_recipients'
メッセージのブラインドカーボンコピーを送信する電子メールアドレスを、セミコロン区切りのリストで指定します。ブラインドコピーの受信者リストのデータ型は varchar(max) です。このパラメーターは省略可能ですが、@recipients、@copy_recipients、または @blind_copy_recipients のうち少なくとも 1 つを指定する必要があります。いずれも指定しない場合、sp_send_dbmail ではエラーが返されます。
[ @from_address= ] 'from_address'
電子メールメッセージの差出人アドレスの値を指定します。これは、メールプロファイルの設定を上書きするためのオプションのパラメーターです。このパラメーターのデータ型は varchar(MAX) です。上書きが許可されるかどうかは、SMTP のセキュリティ設定によって決まります。パラメーターを指定しなかった場合の既定値は NULL です。
[ @reply_to= ] 'reply_to'
電子メールメッセージの返信先アドレスの値を指定します。有効な値として電子メールアドレスが 1 つだけ許可されます。これは、メールプロファイルの設定を上書きするためのオプションのパラメーターです。このパラメーターのデータ型は 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) です。既定では、データベースメールの添付ファイルは 1 ファイルにつき 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 の場合、データベースメールでは任意のファイル名が作成されます。
[ @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 の場合、データベースメールでは本文にクエリのエラーメッセージを含めた電子メールメッセージが送信されます。このパラメーターの値が 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 です。

注
大量のデータを扱っているときに @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 変数に格納されます。

結果セット

成功すると、"メールがキューに登録されました。" というメッセージが返されます。

説明

使用の前に、データベースメール構成ウィザードまたは sp_configure を使用して、データベースメールを有効にする必要があります。

sysmail_stop_sp では、外部プログラムで使用される Service Broker オブジェクトを停止することで、データベースメールを停止します。 sysmail_stop_sp を使用してデータベースメールを停止しても、sp_send_dbmail では引き続きメールを受信します。データベースメールを開始するには、sysmail_start_sp を使用します。

@profile を指定しない場合、sp_send_dbmail では既定のプロファイルが使用されます。電子メールメッセージを送信するユーザーに既定のプライベートプロファイルがある場合、データベースメールではそのプロファイルが使用されます。ユーザーが既定のプライベートプロファイルを所持していない場合、sp_send_dbmail によって既定のパブリックプロファイルが使用されます。ユーザーの既定のプライベートプロファイルも既定のパブリックプロファイルも存在しない場合、sp_send_dbmail がエラーを返します。

sp_send_dbmail では、内容のない電子メールメッセージはサポートされません。電子メールメッセージを送信するには、@body、@query、@file_attachments、または @subject の少なくとも 1 つを指定する必要があります。いずれも指定しない場合、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 を実行すると、データベースメールではユーザーの操作に従い変更がコミットまたはロールバックされます。内側のトランザクションは開始されません。

権限

sp_send_dbmail の実行権限は、既定では msdb データベースにおける DatabaseMailUser データベースロールのすべてのメンバーに許可されています。ただし、メッセージを送信するユーザーに、要求されたプロファイルを使用する権限がない場合、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 で、このメッセージでは DueDate が 2004 年 4 月 30 日から 2 日以内となっている作業指示の番号を表示するクエリが実行されます。データベースメールでは、この結果がテキストファイルとして添付されます。

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 で、このメッセージには DueDate が 2004 年 4 月 30 日から 2 日以内となっている作業指示を表示する 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
              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' ;

次の方法で共有

sp_send_dbmail (Transact-SQL)

構文

引数

リターンコード値

結果セット

説明

権限

使用例

A. 電子メールメッセージを送信する

B. 電子メールメッセージをクエリの結果と共に送信する

C. HTML 形式の電子メールメッセージを送信する

関連項目

参照

概念

その他のリソース

次の方法で共有

sp_send_dbmail (Transact-SQL)

構文

引数

リターン コード値

結果セット

説明

権限

使用例

A. 電子メール メッセージを送信する

B. 電子メール メッセージをクエリの結果と共に送信する

C. HTML 形式の電子メール メッセージを送信する

関連項目

参照

概念

その他のリソース

リターンコード値

A. 電子メールメッセージを送信する

B. 電子メールメッセージをクエリの結果と共に送信する

C. HTML 形式の電子メールメッセージを送信する