SAS 9.1 Language Reference Dictionary, Volumes 1, 2 and 3

2017-07-07 02:10:07

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

Valid: Anywhere

Category: Data Access

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 .

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 email 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.

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 SAS National Language Support (NLS): User s Guide .

TO= to-address
- specifies the primary recipient(s) 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.

CC= cc-address
- specifies the recipient(s) 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>"

BCC= bcc-address
- specifies the recipient(s) 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>"

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. Specify this option, for example, 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>"

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.

ATTACH= filename.ext ATTACH= ( filename.ext attachment-options )
- specifies the physical name of the file(s) 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. For valid encoding values, see Encoding Values in SAS Language Elements in SAS National Language Support (NLS): User s 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")
    - 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. For valid encoding values, see Encoding Values in SAS Language Elements in SAS National Language Support (NLS): User s Guide .
    - CAUTION:
      - Do not specify EBCDIC encoding values, because the SMTP e-mail interface does not support EBCDIC.

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, abort, 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_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.

!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_BCC! bcc-address '
- replaces the current blind copied recipient address(es) with addresses . These recipients are not visible to those 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_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_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_ATTACH! filename.ext ATTACH=( filename.ext attachment-options )
- replaces the physical name of the file(s) 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.
    - 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 SAS National Language Support (NLS): User s 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 :
      
      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. For example, the following 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. For valid encoding values, see Encoding Values in SAS Language Elementsg in SAS National Language Support (NLS): User s Guide .
    - CAUTION:
      - Do not specify EBCDIC encoding values, because the SMTP e-mail interface does not support EBCDIC.

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!
- aborts 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

Overview 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, then submit SAS statements in a DATA step or in SCL code. This 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(s), 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, abort, or start a new message.

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 aborts 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;