Statements

FILENAME Statement, EMAIL (SMTP) Access Method

Enables you to send electronic mail programmatically from SAS using the SMTP (Simple Mail Transfer Protocol) e-mail interface.

Valid:	Anywhere
Category:	Data Access

Syntax
Arguments
E-mail Options
PUT Statement Syntax for EMAIL (SMTP) Access Method
Details
Examples
	Example 1: Sending E-mail with an Attachment Using a DATA Step
	Example 2: Using Conditional Logic in a DATA Step
	Example 3: Sending Procedure Output in E-mail
	Example 4: Creating and E-mailing an Image
See Also

Syntax

FILENAME fileref EMAIL <'address' ><email-options>;

Arguments

fileref: is a valid file reference. The fileref is a name that is temporarily assigned to an external file or to a device type. Note that the fileref cannot exceed eight characters.
EMAIL: specifies the EMAIL device type, which provides the access method that enables you to send electronic mail programmatically from SAS. In order to use SAS to send a message to an SMTP server, you must enable SMTP e-mail. For more information, see The SMTP E-Mail Interface in SAS Language Reference: Concepts.
'address': is the e-mail address to which you want to send the message. You must enclose the address in quotation marks. Specifying an address as a FILENAME statement argument is optional if you specify the TO= e-mail option or the PUT statement !EM_TO! directive, which will override an address specification.

E-mail Options

You can use any of the following e-mail options in the FILENAME statement to specify attributes for the electronic message.

Note: You can also specify these options in the FILE statement. E-mail options that you specify in the FILE statement override any corresponding e-mail options that you specified in the FILENAME statement. [cautionend]

ATTACH='filename.ext' | ATTACH= ('filename.ext' attachment-options)

specifies the physical name of the file or files to be attached to the message and any options to modify attachment specifications. The physical name is the name that is recognized by the operating environment. Enclose the physical name in quotation marks. To attach more than one file, enclose the group of files in parentheses, enclose each file in quotation marks, and separate each with a space. Here are examples:

attach="/u/userid/opinion.txt"

attach=('C:\Status\June2001.txt' 'C:\Status\July2001.txt')

attach="user.misc.pds(member)"

The attachment-options include the following:

CONTENT_TYPE='content/type'

specifies the content type for the attached file. You must enclose the value in quotation marks. If you do not specify a content type, SAS tries to determine the correct content type based on the filename. For example, if you do not specify a content type, a filename of home.html is sent with a content type of text/html.

Aliases:

CT= and TYPE=

Default:

If SAS cannot determine a content type based on the filename and extension, the default value is text/plain.

ENCODING='encoding-value'

specifies the text encoding of the attachment that is read into SAS. You must enclose the value in quotation marks.

See Also:

Encoding Values in SAS Language Elements in the SAS National Language Support (NLS): Reference Guide

EXTENSION='extension'

specifies a different file extension to be used for the specified attachment. You must enclose the value in quotation marks. This extension is used by the recipient's e-mail program for selecting the appropriate utility to use for displaying the attachment. For example, the following results in the attachment home.html being received as index.htm:

attach=("home.html" name="index" ext="htm")

Note: If you specify extension="", the specified attachment will have no file extension. [cautionend]

Alias:

EXT=

NAME='filename'

specifies a different name to be used for the specified attachment. You must enclose the value in quotation marks. For example, the following results in the attachment home.html being received as index.html:

attach=("home.html" name="index")

OUTENCODING='encoding-value'

specifies the resulting text encoding for the attachment to be sent. You must enclose the value in quotation marks.

Restriction:	Do not specify EBCDIC encoding values, because the SMTP e-mail interface does not support EBCDIC.
See Also:	Encoding Values in SAS Language Elements in the SAS National Language Support (NLS): Reference Guide

BCC='bcc-address'

specifies the recipient or recipients that you want to receive a blind copy of the electronic mail. Individuals that are listed in the bcc field will receive a copy of the e-mail. The BCC field does not appear in the e-mail header, so that these e-mail addresses cannot be viewed by other recipients.

If a BCC address contains more than one word, then enclose it in quotation marks. To specify more than one address, you must enclose the group of addresses in parentheses, enclose each address in quotation marks, and separate each address with a space. To specify a real name as well as an address, enclose the address in angle brackets (< >). Here are examples:

bcc="joe@site.com"

bcc=("joe@site.com" "jane@home.net")

bcc="Joe Smith <joe@site.com>"

CC='cc-address'

specifies the recipient or recipients to receive a copy of the e-mail message. You must enclose an address in quotation marks. To specify more than one address, enclose the group of addresses in parentheses, enclose each address in quotation marks, and separate each address with a space. To specify a real name as well as an address, enclose the address in angle brackets (< >). Here are examples:

cc='joe@site.com'

cc=("joe@site.com" "jane@home.net")

cc="Joe Smith <joe@site.com>"

CONTENT_TYPE='content/type'

specifies the content type for the message body. If you do not specify a content type, SAS tries to determine the correct content type. You must enclose the value in quotation marks.

Aliases:

CT= and TYPE=

Default:

text/plain

ENCODING='encoding-value'

specifies the text encoding to use for the message body. For valid encoding values, see Encoding Values in SAS Language Elements in the SAS National Language Support (NLS): Reference Guide.

FROM='from-address'

specifies the e-mail address of the author of the message that is being sent. The default value for FROM= is the e-mail address of the user who is running SAS. For example, specify this option when the person who is sending the message from SAS is not the author. You must enclose an address in quotation marks. You can specify only one e-mail address. To specify the author's real name along with the address, enclose the address in angle brackets (< >). Here are examples:

from='martin@home.com'

from="Brad Martin <martin@home.com>"

Requirement:

The FROM option is required if the EMAILFROM System Option system option is set.

LRECL=lrecl

where lrecl is the logical record length of the data.

Default:	256
Interaction:	Alternatively, you can specify a global logical record length by using the LRECL= System Option.

IMPORTANCE='LOW' | 'NORMAL' | 'HIGH'

specifies the priority of the e-mail message. You must enclose the value in quotation marks. You can specify the priority in the language that matches your session encoding. However, SAS will translate the priority into English because the actual message header must contain English in accordance with the RFC-2076 specification (Common Internet Message Headers). Here are examples:

filename inventory email 'name@mycompany.com' importance='high';

filename inventory email 'name@mycompany.com' importance='hoch';

Default:

NORMAL

REPLYTO='replyto-address'

specifies the e-mail address(es) for who will receive replies. You must enclose an address in quotation marks. To specify more than one address, enclose the group of addresses in parentheses, enclose each address in quotation marks, and separate each address with a space. To specify a real name along with an address, enclose the address in angle brackets (< >). Here are examples:

replyto='hiroshi@home.com'

replyto=('hiroshi@home.com' 'akiko@site.com')

replyto="Hiroshi Mori <mori@site.com>"

SUBJECT=subject

specifies the subject of the message. If the subject contains special characters or more than one word (that is, it contains at least one blank space), you must enclose the text in quotation marks. Here are examples:

subject=Sales

subject="June Sales Report"

Note: If you do not enclose a one-word subject in quotation marks, it is converted to uppercase. [cautionend]

TO='to-address'

specifies the primary recipient or recipients of the e-mail message. You must enclose the address in quotation marks. To specify more than one address, enclose the group of addresses in parentheses, enclose each address in quotation marks, and separate each address with a space. To specify a real name as well as an address, enclose the address in angle brackets (< >). Here are examples:

to='joe@site.com'

to=("joe@site.com" "jane@home.net")

to="Joe Smith <joe@site.com>"

Tip:	Specifying TO= overrides the 'address' argument.

PUT Statement Syntax for EMAIL (SMTP) Access Method

In the DATA step, after using the FILE statement to define your e-mail fileref as the output destination, use PUT statements to define the body of the message. For example,

filename mymail email 'martin@site.com' subject='Sending Email';

data _null_;
   file mymail;
   put 'Hi';
   put 'This message is sent from SAS...';
run;

You can also use PUT statements to specify e-mail directives that override the attributes of your message (the e-mail options like TO=, CC=, SUBJECT=, CONTENT_TYPE=, ATTACH=), or to perform actions such as send, end abnormally, or start a new message. Specify only one directive in each PUT statement; each PUT statement can contain only the text that is associated with the directive that it specifies.

The directives that change the attributes of a message are as follows:

'!EM_ATTACH! 'filename.ext' | ATTACH=('filename.ext' attachment-options)'

replaces the physical name of the file or files to be attached to the message and any options to modify attachment specifications. The physical name is the name that is recognized by the operating environment. The directive must be enclosed in quotation marks, and the physical name must be enclosed in quotation marks. To attach more than one file, enclose the group of files in parentheses, enclose each file in quotation marks, and separate each with a space. Here are examples:

put '!em_attach! /u/userid/opinion.txt';

put '!em_attach! ("C:\Status\June2001.txt" "C:\Status\July2001.txt")';

put '!em_attach! user.misc.pds(member)';

The attachment-options include the following:

CONTENT_TYPE='content/type'

Aliases:

CT= and TYPE=

Default:

If SAS cannot determine a content type based on the filename and extension, the default value is text/plain.

ENCODING='encoding-value'

specifies the text encoding to use for the attachment as it is read into SAS. You must enclose the value in quotation marks. For valid encoding values, see Encoding Values in SAS Language Elements in the SAS National Language Support (NLS): Reference Guide.

EXTENSION='extension'

put '!em_attach! ("home.html" name="index" ext="htm")';

Alias:

EXT=

Default:

TXT

NAME='filename'

put '!em_attach! ("home.html" name="index")';

OUTENCODING='encoding-value'

specifies the resulting text encoding for the attachment to be sent. You must enclose the value in quotation marks.

Restriction:	Do not specify EBCDIC encoding values, because the SMTP e-mail interface does not support EBCDIC.
See Also:	Encoding Values in SAS Language Elements in the SAS National Language Support (NLS): Reference Guide

'!EM_BCC! bcc-address'

replaces the current blind copied recipient address(es) with addresses. These recipients are not visible to the recipients in the !EM_TO! or !EM_CC! addresses. If you want to specify more than one address, then you must enclose the group of addresses in parentheses, enclose each address in quotation marks, and separate each address with a space. To specify real names along with addresses, enclose the address in angle brackets (< >). Here are examples:

put '!em_bcc! joe@site.com';

put '!em_bcc! ("joe@site.com" "jane@home.net")';

put '!em_bcc! Joe Smith <joe@site.com>';

'!EM_CC! cc-address'

replaces the current copied recipient address(es). The directive must be enclosed in quotation marks. To specify more than one address, enclose the group of addresses in parentheses, enclose each address in quotation marks, and separate each address with a space. To specify real names along with addresses, enclose the address in angle brackets (< >). Here are examples:

put '!em_cc! joe@site.com';

put '!em_cc! ("joe@site.com" "jane@home.com")';

put '!em_cc! Joe Smith <joe@site.com>';

'!EM_FROM! from-address'

replaces the current address of the author of the message being sent, which could be either the default or the one specified by the FROM= e-mail option. The directive must be enclosed in quotation marks. You can specify only one e-mail address. To specify the author's real name along with the address, enclose the address in angle brackets (< >). Here are examples:

put '!em_from! martin@home.com';

put '!em_from! Brad Martin <martin@home.com>';

'!EM_IMPORTANCE! LOW | NORMAL | HIGH'

specifies the priority of the e-mail message. The directive must be enclosed in quotation marks. You can specify the priority in the language that matches your session encoding. However, SAS will translate the priority into English because the actual message header must contain English in accordance with the RFC-2076 specification (Common Internet Message Headers). Here are examples:

put '!em_importance! high';

put '!em_importance! haut';

Default:

NORMAL

'!EM_REPLYTO! replyto-address'

replaces the current address(es) of who will receive replies. The directive must be enclosed in quotation marks. To specify more than one address, enclose the group of addresses in parentheses, enclose each address in quotation marks, and separate each address with a space. To specify a real name along with an address, enclose the address in angle brackets (< >). Here are examples:

put '!em_replyto! hiroshi@home.com';

put '!em_replyto! ("hiroshi@home.com" "akiko@site.com")';

put '!em_replyto! Hiroshi Mori <mori@site.com>';

'!EM_SUBJECT! subject'

replaces the current subject of the message. The directive must be enclosed in quotation marks. If the subject contains special characters or more than one word (that is, it contains at least one blank space), you must enclose the text in quotation marks. Here are examples:

put '!em_subject! Sales';

put '!em_subject! "June Sales Report"';

'!EM_TO! to-address'

replaces the current primary recipient address(es). The directive must be enclosed in quotation marks. To specify more than one address, enclose the group of addresses in parentheses, enclose each address in quotation marks, and separate each address with a space. To specify a real name along with an address, enclose the address in angle brackets (< >). Here are examples:

put '!em_to! joe@site.com';

put '!em_to! ("joe@site.com" "jane@home.net")';

put '!em_to! Joe Smith <joe@site.com>';

Tip:	Specifying !EM_TO! overrides the 'address' argument and the TO= e-mail option.

Here are the directives that perform actions:

'!EM_SEND!': sends the message with the current attributes. By default, SAS sends a message when the fileref is closed. The fileref closes when the next FILE statement is encountered or the DATA step ends. If you use this directive, SAS sends the message when it encounters the directive, and again at the end of the DATA step. This directive is useful for writing DATA step programs that conditionally send messages or use a loop to send multiple messages.
'!EM_ABORT!': abnormally end the current message. You can use this directive to stop SAS from automatically sending the message at the end of the DATA step. By default, SAS sends a message for each FILE statement.
'!EM_NEWMSG!': clears all attributes of the current message that were set using PUT statement directives.

Details

You can send electronic mail programmatically from SAS using the EMAIL (SMTP) access method. To send e-mail to an SMTP server, you first specify the SMTP e-mail interface with the EMAILSYS system option, use the FILENAME statement to specify the EMAIL device type, and then submit SAS statements in a DATA step or in SCL code. The e-mail access method has several advantages:

You can use the logic of the DATA step or SCL to subset e-mail distribution based on a large data set of e-mail addresses.
You can automatically send e-mail upon completion of a SAS program that you submitted for batch processing.
You can direct output through e-mail based on the results of processing.

In general, DATA step or SCL code that sends e-mail has the following components:

a FILENAME statement with the EMAIL device-type keyword
e-mail options specified in the FILENAME or FILE statement that indicate e-mail recipients, subject, attached file or files, and so on
PUT statements that define the body of the message
PUT statements that specify e-mail directives (of the form !EM_directive!) that override the e-mail options (for example, TO=, CC=, SUBJECT=, ATTACH=) or perform actions such as send, end abnormally, or start a new message.

You can use encoded e-mail passwords. When a password is encoded with PROC PWENCODE, the output string includes a tag that identifies the string as having been encoded. An example of a tag is {sas001}. The tag indicates the encoding method. Encoding a password enables you to avoid e-mail access authentication with a password in plaintext. Passwords that start with "{sas" trigger an attempt to be decoded. If the decoding succeeds, then that decoded password is used. If the decoding fails, then the password is used as is. For more information, see PROC PWENCODE in the Base SAS Procedures Guide.

Examples

Example 1: Sending E-mail with an Attachment Using a DATA Step

In order to share a copy of your SAS configuration file with another user, you could send it by submitting the following program. The e-mail options are specified in the FILENAME statement:

filename mymail email "JBrown@site.com"
   subject="My SAS Configuration File"
   attach="/u/sas/sasv8.cfg";

data _null_;
   file mymail;
   put 'Jim,';
   put 'This is my SAS configuration file.';
   put 'I think you might like the';
   put 'new options I added.';
run;

The following program sends a message and two file attachments to multiple recipients. For this example, the e-mail options are specified in the FILE statement instead of the FILENAME statement.

filename outbox email "ron@acme.com"; 

data _null_;    
   file outbox    
      to=("ron@acme.com" "humberto@acme.com")    
         /* Overrides value in */     
         /* filename statement */    
      cc=("miguel@acme.com" "loren@acme.com")    
      subject="My SAS Output"    
      attach=("C:\sas\results.out" "C:\sas\code.sas")  
   ;    
   put 'Folks,';    
   put 'Attached is my output from the SAS';    
   put 'program I ran last night.';     
   put 'It worked great!'; 
run;

Example 2: Using Conditional Logic in a DATA Step

You can use conditional logic in a DATA step in order to send multiple messages and control which recipients get which message. For example, in order to send customized reports to members of two different departments, the following program produces an e-mail message and attachments that are dependent on the department to which the recipient belongs. In the program, the following occurs:

In the first PUT statement, the !EM_TO! directive assigns the TO attribute.
The second PUT statement assigns the SUBJECT attribute using the !EM_SUBJECT! directive.
The !EM_SEND! directive sends the message.
The !EM_NEWMSG! directive clears the message attributes, which must be used to clear message attributes between recipients.
The !EM_ABORT! directive abnormally ends the message before the RUN statement causes it to be sent again. The !EM_ABORT! directive prevents the message from being automatically sent at the end of the DATA step.

filename reports email "Jim.Smith@work.com"; 

data _null_;    
   file reports;    
   length name dept $ 21;    
   input name dept;    
   put '!EM_TO! ' name;       
   put '!EM_SUBJECT! Report for ' dept;      
   put name ',';    
   put 'Here is the latest report for ' dept '.' ;    
   if dept='marketing' then    
      put '!EM_ATTACH! c:\mktrept.txt';  
   else  /* ATTACH the appropriate report */       
      put '!EM_ATTACH! c:\devrept.txt';
      put '!EM_SEND!';       
      put '!EM_NEWMSG!';     
      put '!EM_ABORT!';      
   datalines; 
Susan          marketing 
Peter          marketing 
Alma           development 
Andre          development 
;
run;

Example 3: Sending Procedure Output in E-mail

You can use e-mail to send procedure output. This example illustrates how to send ODS HTML in the body of an e-mail message. Note that ODS HTML procedure output must be sent with the RECORD_SEPARATOR (RS) option set to NONE.

filename outbox email
   to='susan@site.com'
   type='text/html'
   subject='Temperature Conversions';

data temperatures;
   do centigrade = -40 to 100 by 10;
      fahrenheit = centigrade*9/5+32;
      output;
   end;
run;

ods html
   body=outbox /* Mail it! */
   rs=none;

title 'Centigrade to Fahrenheit Conversion Table';

proc print;
   id centigrade;
   var fahrenheit;
run;

ods html close;

Example 4: Creating and E-mailing an Image

The following example illustrates how to create a GIF image and send it from SAS in an e-mail message:

filename gsasfile email
   to='Jim@acme.com'
   type='image/gif'
   subject="SAS/GRAPH Output";

goptions dev=gif gsfname=gsasfile;

proc gtestit pic=1; 
run;