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 in: Anywhere
Category: Data Access

Syntax

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 bytes.
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 single or double quotation marks. To specify more than one address, you must enclose the group of addresses in parentheses, enclose each address in single or double quotation marks, and separate each address with either a comma or a space. To specify a real name along with an address, enclose the address in angle brackets (< >). 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. 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.

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.
Alias: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:Encoding Values in SAS Language Elements in 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. The following example results in the attachment home.html being received as index.htm.
attach=("home.html" name="index" ext="htm")
Alias:EXT=
Note:If you specify extension="", the specified attachment will have no file extension.
NAME='filename'
specifies a different name to be used for the specified attachment. You must enclose the value in quotation marks. The following example 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:Encoding Values in SAS Language Elements in SAS National Language Support (NLS): Reference Guide
BCC='bcc-address'
specifies the recipient or recipients that you want to receive a blind carbon copy of the e-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 the address in single or double quotation marks. To specify more than one address, you must enclose the group of addresses in parentheses, enclose each address in single or double quotation marks, and separate each address with either a comma or 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 carbon copy of the e-mail message. You must enclose the address in single or double quotation marks. To specify more than one address, enclose the group of addresses in parentheses, enclose each address in single or double quotation marks, and separate each address with either a comma or 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.
Alias:CT= and TYPE=
Default:text/plain
DELIVERYRECEIPT
specifies that a notification be sent when the e-mail message is delivered to the recipient.
Note:If the recipient’s e-mail client does not support or if the recipient does not allow “delivery receipt” requests, the sender will not get a “delivery receipt” notification when the e-mail is delivered.
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 SAS National Language Support (NLS): Reference Guide.
EXPIRES='dd mon yyyy hh:mm'
specifies the expiration date for the e-mail message.
The format dd mon hh:mm parameters are defined as follows:
dd
is an integer from 01 to 31 that represents the day of the month.
mon
are the first three letters of the month name in English.
yyyy
is a four-digit integer that represents the year.
hh
is the number of hours that range from 00 through 23.
mm
is the number of minutes that range from 00 through 59.
Tip:If the date and time have passed the current date and time, an error message occurs and no e-mail is sent.
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 is set. For more information, see the EMAILFROM System Option in SAS System Options: Reference.
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
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 in SAS System Options: Reference.
READRECEIPT
specifies that a notification be sent when the e-mail message is read by the recipient.
Note:If the recipient’s e-mail client does not support or if the recipient does not allow return “read receipt” requests, the sender will not get a “read receipt” notification when the recipient reads the e-mail.
REPLYTO='replyto-address'
specifies the e-mail address or addresses of who will receive replies. You must enclose the address in single or double quotation marks. To specify more than one address, enclose the group of addresses in parentheses, enclose each address in single or double quotation marks, and separate each address with either a comma or 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.
TO='to-address'
specifies the primary recipient or recipients of the e-mail message. You must enclose the address in single or double quotation marks. To specify more than one address, enclose the group of addresses in parentheses, enclose each address in single or double quotation marks, and separate each address with either a comma or 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 '' argument.

PUT Statement E-Mail Directives

The directives that you can specify in a PUT statement to change the attributes of a message are as follows:

'!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_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'
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.
Alias: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 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. The following example results in the attachment home.html being received as index.htm.
put '!em_attach! ("home.html" name="index" ext="htm")';
Alias:EXT=
Default:TXT
NAME='filename'
specifies a different name to be used for the specified attachment. You must enclose the value in quotation marks. The following example results in the attachment home.html being received as index.html.
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:Encoding Values in SAS Language Elements in SAS National Language Support (NLS): Reference Guide
'!EM_BCC! bcc-address'
specifies the recipient or recipients that you want to receive a blind carbon copy of the e-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 the address in single or double quotation marks. To specify more than one address, you must enclose the group of addresses in parentheses, enclose each address in single or double quotation marks, and separate each address with either a comma or a space. To specify a real name as well as an address, enclose the address in angle brackets (< >).
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'
specifies the recipient or recipients to receive a carbon copy of the e-mail message. You must enclose the address in single or double quotation marks. To specify more than one address, enclose the group of addresses in parentheses, enclose each address in single or double quotation marks, and separate each address with either a comma or a space. To specify a real name as well as an address, 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_DELIVERYRECEIPT!'
specifies that a notification be sent when the e-mail message is delivered to the recipient.
Note:If the recipient’s e-mail client does not support or if the recipient does not allow “delivery receipt” requests, the sender will not get a “delivery receipt” notification when the e-mail is delivered.
'!EM_EXPIRES! dd mon yyyy hh:mm'
replaces the current expiration date for the e-mail message. Here are examples:
put '!em_expires! 15 Aug 2010 08:00';
put '!em_expires! 28 Feb 2011 23:00';
The format dd mon hh:mm parameters are defined as follows:
dd
is an integer from 01 to 31 that represents the day of the month.
mon
are the first three letters of the month name in English.
yyyy
is a four-digit integer that represents the year.
hh
is the number of hours that range from 00 through 23.
mm
is the number of minutes that range from 00 through 59.
Tip:If the date and time have passed the current date and time, an error message occurs and no e-mail is sent.
'!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_NEWMSG!'
clears all attributes of the current message that were set using PUT statement directives.
'!EM_READRECEIPT!'
specifies that a notification be sent when the e-mail message is read by the recipient.
Note:If the recipient’s e-mail client does not support or if the recipient does not allow “read receipt” requests, the sender will not get a “read receipt” notification when the recipient reads the e-mail.
'!EM_REPLYTO! replyto-address'
specifies the e-mail address or addresses of who will receive replies. You must enclose the address in single or double quotation marks. To specify more than one address, enclose the group of addresses in parentheses, enclose each address in single or double quotation marks, and separate each address with either a comma or 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_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_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'
specifies the primary recipient or recipients of the e-mail message. You must enclose the address in single or double quotation marks. To specify more than one address, enclose the group of addresses in parentheses, enclose each address in single or double quotation marks, and separate each address with either a comma or a space. To specify a real name as well as 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.

Details

The Basics

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.
For e-mail messages that you send to another time zone, you can use the EMAILUTCOFFSET= system option to ensure that the e-mail message has the UTC offset that represents your local time. You might use this option this if the time on your computer is not set to a time that uses a UTC offset or your computer does not account for daylight savings time. The UTC offset specified in the EMAILUTCOFFSET= system option adds or replaces a UTC offset to the time in the e-mail's Date: header field. For more information, see the EMAILUTCOFFSET= System Option in SAS System Options: Reference.

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. Here is an 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.
For a list of e-mail directives, see PUT Statement E-Mail Directives.

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;

Example 4: Creating and E-mailing an Image

The following example illustrates how to create a GIF image and send it from SAS as an attachment to 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;