sp_send_dbmail (Transact-SQL)

指定した受信者に電子メール メッセージを送信します。メッセージには、クエリ結果セットまたは添付ファイル、あるいはその両方を含めることができます。メールがデータベース メール キューに正常に配置されると、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 の場合は成功を示します。それ以外の値は失敗を示します。失敗したステートメントのエラー コードは @@ERROR 変数に格納されます。

結果セット

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

説明

使用の前に、データベース メール構成ウィザードまたは 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 = 'AdventureWorks2008R2 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 = 'AdventureWorks2008R2 Administrator',
    @recipients = 'danw@Adventure-Works.com',
    @query = 'SELECT COUNT(*) FROM AdventureWorks2008R2.Production.WorkOrder
                  WHERE DueDate > ''2006-04-30''
                  AND  DATEDIFF(dd, ''2006-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 AdventureWorks2008R2.Production.WorkOrder as wo
              JOIN AdventureWorks2008R2.Production.Product AS p
              ON wo.ProductID = p.ProductID
              WHERE DueDate > '2006-04-30'
                AND DATEDIFF(dd, '2006-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' ;

関連項目

参照

データベース メールと SQL Mail のストアド プロシージャ (Transact-SQL)

sp_addrolemember (Transact-SQL)

概念

データベース メール

データベース メール プロファイル

その他の技術情報

データベース メール構成ウィザード