Using External Files and Devices

Sending Electronic Mail Using the FILENAME Statement (EMAIL)

Advantages of Sending Electronic Mail from within SAS

SAS lets you send electronic mail using SAS functions in a DATA step or in SCL. Sending e-mail from within SAS enables you to do the following:

Use the logic of the DATA step or SCL to subset e-mail distribution based on a large data set of e-mail addresses.
Send e-mail automatically upon completion of a SAS program that you submitted for batch processing.
Direct output through e-mail based on the results of processing.
Send e-mail messages from within a SAS/AF frame application, customizing the user interface.

Initializing Electronic Mail

By default, SAS uses SMTP (Simple Mail Transfer Protocol) to send e-mail. SMTP, unlike some external scripts, supports attachments. This default is specified by the EMAILSYS system option. For information about how to change the e-mail protocol, see EMAILSYS System Option: UNIX.

Before you can send e-mail from within SAS, your system administrator might need to set the EMAILHOST system option to point to the SMTP server. For more information about the EMAILHOST system option, see SAS Language Reference: Dictionary.

Components of the DATA Step or SCL Code Used to Send E-mail

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

a FILENAME statement with the EMAIL device-type keyword
options specified in the FILENAME or FILE statements indicating the e-mail recipients, subject, and any attached files
PUT statements that contain the body of the message
PUT statements that contain special e-mail directives (of the form !EM_directive!) that can override the e-mail attributes (TO, CC, BCC, SUBJECT, ATTACH) or perform actions (such as SEND, ABORT, and start a NEWMSG)

Syntax of the FILENAME Statement for Electronic Mail

To send electronic mail from a DATA step or SCL, issue a FILENAME statement of the following form:

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

The FILENAME statement accepts the following email-options:

fileref

is a valid fileref.

'address'

is the destination e-mail address of the user to which you want to send e-mail. You must specify an address here, but you can override its value with the TO e-mail option.

email-options

can be any of the following:

TO=to-address

specifies the primary recipients of the electronic mail. If an address contains more than one word, enclose it 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. For example, to='joe@someplace.org' and to=("joe@smplc.org" "jane@diffplc.org") are valid TO values.

Note: You can send an e-mail without specifying a recipient in the TO= option as long as you specify a recipient in either the CC= or BCC= option. [cautionend]

CC=cc-address

specifies the recipients you want to receive a copy of the electronic mail. If an address contains more than one word, enclose it 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. For example, cc='joe@someplace.org' and cc=("joe@smplc.org" "jane@diffplc.org") are valid CC values.

BCC=bcc-address

specifies the recipients you want to receive a blind copy of the electronic mail. Individuals 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, enclose it 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. For example, bcc='joe@someplace.org' and bcc=("joe@smplc.org" "jane@diffplc.org") are valid BCC values.

SUBJECT='subject'

specifies the subject of the message. If the subject text is longer than one word (that is, it contains at least one blank space), you must enclose it in quotation marks. You also must use quotation marks if the subject contains any special characters. For example, subject=Sales and subject='June Report' are valid subjects. Any subject not enclosed in quotation marks is converted to uppercase.

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

specifies the physical name of the files to be attached to the message and any options to modify attachment specifications. Enclose filename.ext in quotation marks. To attach more than one file, enclose the group of filenames in parentheses. For example, attach='/u/userid/opinion.txt' and attach=("june98.txt" "july98.txt") are valid file attachments.

By default, SMTP e-mail attachments are truncated at 256 characters. To send longer attachments, you can specify the LRECL= and RECFM= options from the FILENAME statement as the attachment-options. For more information about the LRECL= and RECFM= options, see FILENAME Statement: UNIX.

For more information about the options that are valid when you are using SMTP, see FILENAME Statement, EMAIL (SMTP) Access Method in SAS Language Reference: Dictionary.

Specifying E-mail Options in the FILE Statement

You can also specify the email-options in the FILE statement inside the DATA step. Options that you specify in the FILE statement override any corresponding options that you specified in the FILENAME statement.

Defining the Body of the Message

In your 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.

Specifying E-mail Directives in the PUT Statement

You can also use PUT statements to specify e-mail directives that change the attributes of your electronic message or perform actions with it. Specify only one directive in each PUT statement; each PUT statement can contain only the text associated with the directive it specifies.

The following are the directives that change the attributes of your message:

!EM_TO! addresses: Replace the current primary recipient addresses with addresses. In the PUT statement, specify addresses without single quotation marks.
!EM_CC! addresses: Replace the current copied recipient addresses with addresses. In the PUT statement, specify addresses without single quotation marks.
!EM_BCC! addresses: Replace the current blind copied recipient addresses with addresses. In the PUT statement, specify addresses without single quotation marks.
!EM_SUBJECT! subject: Replace the current subject of the message with subject.
!EM_ATTACH! pathname: Replace the names of any attached files with pathname.

The following 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.
!EM_ABORT!: Aborts the current message. You can use this directive to stop SAS from automatically sending the message at the end of the DATA step.
!EM_NEWMSG!: Clears all attributes of the current message, including TO, CC, SUBJECT, ATTACH, and the message body.

Example: Sending E-mail from the DATA Step

Suppose that you want to share a copy of your config.sas file with your coworker Jim, whose user ID is JBrown. If your e-mail program handles alias names and attachments, you could send it by submitting the following DATA step:

filename mymail email 'JBrown' 
         subject='My CONFIG.SAS file'
         attach='config.sas';

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

The following example sends a message and two attached files to multiple recipients. It specifies the e-mail options in the FILE statement instead of the FILENAME statement:

filename outbox email 'ron@acme.com';

data _null_;
  file outbox

        /* Overrides value in filename statement */
     to=('ron@acme.com' 'lisa@acme.com')
     cc=('margaret@yourcomp.com' 
         'lenny@laverne.abc.com')
     subject='My SAS output'
     attach=('results.out' 'code.sas')
     ;
  put 'Folks,';
  put 'Attached is my output from the 
      SAS program I ran last night.';
  put 'It worked great!';
run;

You can use conditional logic in the DATA step to send multiple messages and control which recipients get which message. For example, suppose you want to send customized reports to members of two different departments. If your e-mail program handles alias names and attachments, your DATA step might look like the following:

filename reports email 'Jim';

data _null_;
  file reports;
  infile cards eof=lastobs;
  length name dept $ 21;
  input name dept;

     /* Assign the TO attribute      */
  put '!EM_TO!' name;
   
     /* Assign the SUBJECT attribute */
  put '!EM_SUBJECT! Report for ' dept;  
   
  put name ',';
  put 'Here is the latest report for ' dept '.';

     /* ATTACH the appropriate report */
  if dept='marketing' then
      put '!EM_ATTACH! mktrept.txt';
  else                                  
    
    put '!EM_ATTACH! devrept.txt';
  
     /* Send the message */
  put '!EM_SEND!';                      
    
    /* Clear the message attributes */
  put '!EM_NEWMSG!';                    
    
  return;

   /* Abort the message before the */ 
   /*   RUN statement causes it to */ 
   /*   be sent again.            */
lastobs: put '!EM_ABORT!';              
    
  datalines;
Susan          marketing
Jim            marketing
Rita           development
Herb           development
;
run;

The resulting e-mail message and its attachments are dependent on the department to which the recipient belongs.

Note: You must use the !EM_NEWMSG! directive to clear the message attributes between recipients. The !EM_ABORT! directive prevents the message from being automatically sent at the end of the DATA step. [cautionend]

Example: Sending E-mail Using SCL Code

The following example is the SCL code behind a frame entry design for e-mail. The frame entry includes several text entry fields that let the user enter information:

mailto	the user ID to send mail to
copyto	the user ID to copy (CC) the mail to
attach	the name of a file to attach
subject	the subject of the mail
line1	the text of the message

The frame entry also contains a button named SEND that causes this SCL code (marked by the send: label) to execute.

send:

   /* set up a fileref */
rc = filename('mailit','userid','email');

   /* if the fileref was successfully set up 
      open the file to write to */
if rc = 0 then do;
      fid = fopen('mailit','o');
      if fid > 0 then do;

         /* fput statements are used to 
            implement writing the
            mail and the components such as 
            subject, who to mail to, and so on. */
      fputrc1  = fput(fid,line1);
      rc = fwrite(fid);

      fputrc2  = fput(fid,'!EM_TO! '||mailto);
      rc = fwrite(fid);
      fputrc3  = fput(fid,'!EM_CC! '||copyto);
      rc = fwrite(fid);

      fputrc4  = fput(fid,'!EM_ATTACH! '||attach);
      rc = fwrite(fid);
      fputrc5  = fput(fid,'!EM_SUBJECT! '||subject);
      rc = fwrite(fid);

         closerc  = fclose(fid);
      end;
   end;
return;

cancel:
   call execcmd('end');
return;

Top of Page