sp_send_dbmail(Transact-SQL)

아티클
12/20/2023

적용 대상:SQL Server Azure SQL Managed Instance

지정된 수신자에게 전자 메일 메시지를 보냅니다. 메시지에 쿼리 결과 집합, 파일 첨부 파일 또는 둘 다 포함될 수 있습니다. 메일이 데이터베이스 메일 큐 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 = ] 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) 형식입니다. 이 매개 변수는 선택 사항이지만 @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'

전자 메일 메시지의 '보낸 사람 주소' 값입니다. 메일 프로필의 설정을 재정의하는 데 사용되는 선택적 매개 변수입니다. 이 매개 변수는 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 = ] '중요도'

메시지의 중요도입니다. 매개 변수는 varchar(6) 형식입니다. 매개 변수는 다음 값 중 하나를 포함할 수 있습니다.

Low
Normal (기본값)
High

[ @sensitivity = ] '민감도'

메시지의 민감도입니다. 매개 변수는 varchar(12) 형식입니다. 매개 변수는 다음 값 중 하나를 포함할 수 있습니다.

Normal (기본값)
Personal
Private
Confidential

[ @file_attachments = ] N'file_attachments'

전자 메일 메시지에 첨부할 파일 이름의 세미콜론으로 구분된 목록입니다. 목록의 파일을 절대 경로로 지정해야 합니다. 첨부 파일 목록은 nvarchar(max) 형식입니다. 기본적으로 데이터베이스 메일 파일 첨부 파일을 파일당 1MB로 제한합니다.

Important

이 매개 변수는 로컬 파일 시스템에 액세스할 수 없으므로 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 비트 형식이며 기본값은 .입니다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_file1 이 매개 변수인 경우 NULL데이터베이스 메일 임의의 파일 이름을 만듭니다.

[ @query_result_header = ] query_result_header

쿼리 결과에 열 머리글을 포함할 것인지 여부를 지정합니다. query_result_header 값은 비트 형식입니다. 값이면 1쿼리 결과에 열 머리글이 포함됩니다. 값이면 0쿼리 결과에 열 머리글이 포함되지 않습니다. 이 매개 변수의 기본값은 .입니다 1. 이 매개 변수는 @query 지정된 경우에만 적용됩니다.

@query_result_header 설정하고 @query_no_truncate 10 설정할 때 다음 오류가 발생할 수 있습니다.

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 비트이며 기본값은 .입니다0. 이 매개 변수인 경우 0저장 프로시저의 sp_send_dbmail 실행은 콘솔에서 쿼리 실행의 결과로 반환된 메시지를 출력합니다. 이 매개 변수인 경우 1저장 프로시저를 sp_send_dbmail 실행해도 콘솔에 쿼리 실행 메시지가 인쇄되지 않습니다.

[ @append_query_error = ] append_query_error

@query 인수에 지정된 쿼리에서 오류가 반환될 때 전자 메일을 보낼지 여부를 지정합니다. @append_query_error 비트이며 기본값은 .입니다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 값은 비트 형식입니다. 값을 0 지정하거나 지정하지 않으면 쿼리의 열이 256자로 잘립니다. 값이면 1쿼리의 열이 잘리지 않습니다. 이 매개 변수의 기본값은 .입니다 0.

참고 항목

많은 양의 데이터 와 함께 사용하는 경우 @query_no_truncate 옵션은 추가 리소스를 사용하고 서버 성능을 저하할 수 있습니다.

[ @query_result_no_padding = ] query_result_no_padding

비트 형식입니다. 기본값은 0입니다. 설정 1하면 쿼리 결과가 패딩되지 않으므로 파일 크기가 줄어들 수 있습니다. @query_result_width 매개 변수로 설정하고 설정하면 @query_result_no_padding 매개 변수가 @query_result_width 매개 변수를 덮어씁니다.@query_result_no_padding1

이 경우 오류가 발생하지 않습니다.

@query_result_no_padding 설정하고 @query_no_truncate1 매개 변수를 제공할 때 다음 오류가 발생할 수 있습니다.

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 설정하고 @query_no_truncate1 매개 변수를 설정하면 오류가 발생합니다.

[ @mailitem_id = ] mailitem_id [ 출력 ]

선택적 출력 매개 변수는 메시지의 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 는 콘텐츠가 없는 전자 메일 메시지를 지원하지 않습니다. 전자 메일 메시지를 보내려면 @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 매개 변수는 세미콜론으로 구분된 전자 메일 주소 목록입니다. 이러한 매개 변수 중 하나 이상을 제공하거나 sp_send_dbmail 오류를 반환해야 합니다.

트랜잭션 컨텍스트 없이 실행하는 sp_send_dbmail 경우 데이터베이스 메일 암시적 트랜잭션을 시작하고 커밋합니다. 기존 트랜잭션 내에서 실행할 sp_send_dbmail 때 데이터베이스 메일 사용자가 변경 내용을 커밋하거나 롤백하는 데 의존합니다. 내부 트랜잭션을 시작하지 않습니다.

사용 권한

데이터베이스에서 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일 이후 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';

sp_send_dbmail(Transact-SQL)

구문

인수

[ @profile_name = ] 'profile_name'

[ @recipients = ] 'recipients'

[ @copy_recipients = ] 'copy_recipients'

[ @blind_copy_recipients = ] 'blind_copy_recipients'

[ @from_address = ] 'from_address'

[ @reply_to = ] 'reply_to'

[ @subject = ] N'subject'

[ @body = ] N'body'

[ @body_format = ] 'body_format'

[ @importance = ] '중요도'

[ @sensitivity = ] '민감도'

[ @file_attachments = ] N'file_attachments'

[ @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 [ 출력 ]

반환 코드 값

결과 집합

설명

사용 권한

예제

A. 전자 메일 메시지 보내기

B. 쿼리 결과와 함께 전자 메일 메시지 보내기

C. HTML 전자 메일 메시지 보내기

피드백

피드백

추가 리소스

sp_send_dbmail(Transact-SQL)

구문

인수

[ @profile_name = ] 'profile_name'

[ @recipients = ] 'recipients'

[ @copy_recipients = ] 'copy_recipients'

[ @blind_copy_recipients = ] 'blind_copy_recipients'

[ @from_address = ] 'from_address'

[ @reply_to = ] 'reply_to'

[ @subject = ] N'subject'

[ @body = ] N'body'

[ @body_format = ] 'body_format'

[ @importance = ] '중요도'

[ @sensitivity = ] '민감도'

[ @file_attachments = ] N'file_attachments'

[ @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 [ 출력 ]

반환 코드 값

결과 집합

설명

사용 권한

예제

A. 전자 메일 메시지 보내기

B. 쿼리 결과와 함께 전자 메일 메시지 보내기

C. HTML 전자 메일 메시지 보내기

관련 콘텐츠

피드백

피드백

추가 리소스