Getting started with SMTP

SMTP, Simple Mail Transfer Protocol, is a standard for sending e-mail over the Internet using TCP/IP.
For more information, see RFC 821

IBM's TCP/IP for MVS comes with a very primitive line-mode TSO command called SMTPNOTE that
allows you to send text-only notes from TSO to any connected Internet or Intranet mail host that
supports SMTP. Once you've used the SMTPNOTE TSO command once, you'll want to use
something more user-friendly. All the SMTPNOTE command does is put a note in SMTP note format
on the JES2 SPOOL. Your TCP/IP SMTP task will pull this item off the spool and send it to the TCP/IP
IP or host destination.

To demonstrate that they didn't put "Simple" in the name SMTP for nothing, here is an example of
creating a SMTP note via a batch job using the IEBGENER utility:

//SENDNOTE EXEC PGM=IEBGENER

//SYSIN DD DUMMY
//SYSPRINT DD SYSOUT=*
//SYSUT2 DD SYSOUT=(B,SMTP)
//SYSUT1 DD *
helo MVSHOST
mail from:
rcpt to:
data
From: MVSUser@MVSHost.xyz.com
To: unixuser@pop3.xyz.com
Subject: Test message from MVS using SMTP

This is a line in the body of the note.

You will need to change:

• "MVSHOST" (on the "helo MVSHOST" line) must match the JES Node name for your system
as defined in your 'SYS1.PARMLIB(IEFSSNxx)' for the VMCF subsystem. If you are a JES2
site, look at any JES2 job log for the node name at the top after "N O D E".
• "unixuser@pop3.xyz.com" to valid destination SMTP e-mail address
• "MVSuser@MVSHost.xyz.com" to a valid TSO user and host

Note: Although you can spoof e-mail by putting anything here, your installation has the
ability to go back and track when you do this. Do not use this ability to spoof e-mail and
think you can't get caught! SMF records are written and with a little research, the mail
spoofer will be found out.

• I intentionally leave the Date: SMTP command off. When IBM's SMTP task processes your
note, it will add the date and time information if not found. I've seen that if the date SMTP
command was not of the right format that MS-Exchange reports the wrong time.

Typically you won't use IEBGENER to send SMTP notes. This is just used for demonstration
purposes. You would usually use a program of some type to send mail from an application that
would fill in the email destination, sender, etc. and then put the item on the JES2 SPOOL.
SMTP links:
 • RFC 821
• A Day In The Life Of An E-Mail Message
• Freeware: Lionel Dyck's XMITIP rexx exec is more user friendly than IBM's SMTPNOTE. It
can be found on his OS/390 freeware page
• Freeware: Computer Application Services, Inc. (CASI) has JES2Mail-Lite. Anyone who
registers on their website can download this product and freely use it to replace, with
enhancements, the IBM SMTP utility.

SMTPNOTE modification
The SMTPNOTE Rexx exec (found in DSN=TCPIP.SEZAINST) as delivered with the TCP/IP for MVS
product, has to be customized by every installation because the hostname and smtpnode variables
are set to an arbitrary value of "YKTVS". TSO/E at version 2.5 and higher has a function that will get
the JES2/3 nodename. If you are at TSO/E 2.5 and higher, you could modify these two variable
settings with this code:
hostname = sysvar(sysnode)
smtpnode = sysvar(sysnode)
I opened an ETR with IBM about the hostname/smtpnode settings and suggested the
sysvar(sysnode) solution. They have created Requirement number REQ00069620 to fix this in a
future version of the product.
Getting started with MIME
MIME, Multipurpose Internet Mail Extensions, is the standard for sending multipart, multimedia, and
binary data using the world-wide Internet e-mail system. MIME is documented in RFC 1341.

To get you started sending simple MIME attachments from MVS, I've taken the simple MIME
example from Mark Grand's MIME Overview and created the following batch job that uses IEBGENER
to send a SMTP note with a MIME text attachment:

//SENDNOTE EXEC PGM=IEBGENER

//SYSIN DD DUMMY
//SYSPRINT DD SYSOUT=*
//SYSUT2 DD SYSOUT=(B,SMTP)
//SYSUT1 DD *
helo MVSHOST
mail from:
rcpt to:
data
From: MVSUser@MVSHost.xyz.com
To: unixuser@pop3.xyz.com
Subject: Test message from MVS using SMTP (with MIME)
MIME-Version: 1.0
Content-type: multipart/mixed;
boundary="simple boundary"

This is the preamble. It is to be ignored, though it is

a handy place for mail composers to include an
explanatory note to non-MIME compliant readers.
--simple boundary

This is implicitly typed plain ASCII text.

--simple boundary
Content-type: text/plain; charset=us-ascii

This is explicitly typed plain ASCII text. It DOES end

with a line break.
--simple boundary--
This is the epilogue. It is also to be ignored.

See the text following the first IEBGENER example for the things you will need to change.
MIME resource links:

• Mark Grand's MIME Overview

• Netscape's MIME page
• All about viewing

Sending binary files from MVS in a MIME attachment

SMTP has restrictions that e-mail only consist of valid ASCII characters and can't handle binary
values embedded in an e-mail. To get past this problem, an Internet standard called RFC 1521 -
5.2. Base64 Content-Transfer-Encoding was developed. To get MVS in the business of sending binary
MIME attachments, we need a program that will encode binary files into the Base 64 encoding
scheme.

I found a Rexx exec called ENBASE64 written by James L. Dean (no relation) that is available in
numerous places on the Internet including in the OS/2 section of shareware.com in a file called
BASE64.ZIP. Here is a local copy of BASE64.ZIP. This ZIP file consists of a few Rexx execs that do
BASE64 processing including one that encodes a file into BASE64 called ENBASE64.CMD

Since ENBASE64.CMD was written using I/O functions that Rexx on MVS doesn't support, it needed
a few modifications to run on MVS. I have created a modified one called enbase64.txt that works on
MVS, VM and also runs on PCs.

To show how we would send binary data from MVS as a MIME attachment, look at the following job
stream that sends a small zip file from MVS to a SMTP mail host.

//*
//** Encode the ZIP file using the ENBASE64 Rexx
exec
//*
//B64 EXEC PGM=IRXJCL,
// PARM='ENBASE64'
//SYSEXEC DD DISP=SHR,DSN=ibmuser.SYSEXEC
//*
//SYSUT1 DD DISP=SHR,DSN=ibmuser.A.ZIP
//SYSUT2 DD DSN=&&BASE64,
// DISP=(,PASS),UNIT=SYSDA,
//
DCB=(LRECL=80,BLKSIZE=8800,RECFM=FB),
// SPACE=(CYL,(5,0),RLSE)
//SYSTSIN DD DUMMY
//SYSTSPRT DD SYSOUT=*
//*
//** Send the note via SMTP (with MIME attachment)
//*
//SENDNOTE EXEC PGM=IEBGENER
//SYSIN DD DUMMY
//SYSPRINT DD SYSOUT=*
//SYSUT2 DD SYSOUT=(B,SMTP)
//SYSUT1 DD *
helo MVSHOST
mail from:
rcpt to:
data
From: MVSUser@MVSHost.xyz.com
To: unixuser@pop3.xyz.com
Subject: Test message from MVS using SMTP (with
ZIP MIME att.)
Mime-Version: 1.0
Content-Type: multipart/mixed; boundary="----
=_NextPart_000_01BD3BAF.A762FD80"

This message is in MIME format. Since your mail

reader does not understand
this format, some or all of this message may not
be legible.

------ =_NextPart_000_01BD3BAF.A762FD80
Content-Type: text/plain; charset="us-ascii"
Content-Transfer-Encoding: 7bit

Attached is a zip file

------ =_NextPart_000_01BD3BAF.A762FD80
Content-Type: application/octet-stream;
name="a.zip"
Content-Transfer-Encoding: base64

/*
// DD DISP=(OLD,PASS),DSN=&&BASE64
// DD *

------ =_NextPart_000_01BD3BAF.A762FD80--
/*

See the text following the first IEBGENER example for the things you will need to change.

You should be able to take the jobstream above, modify the header lines for your shop, send it to a
mail server, process it with a mail reader that can handle MIME and then get the ZIP attached file.
The A.ZIP is a PKZIP file consisting of one file called "A.TXT" which has one line with this value: "A
LINE". If you want to test out the job stream on your system, upload the A.ZIP to your MVS
mainframe in binary form.

You are now ready to send other Binary MIME attachments. See the MIME GIF jobstream that
creates a GIF file with SAS, encodes it and then sends it via a SMTP w/MIME e-mail. For more
information on creating GIF files with SAS, see my SAS GIF page.
XMITB64 - better Base64 MVS (OS/390) program
Although the ENBASE64 Rexx exec is easy to use, it does not handle large files very well. Lionel
Dyck has made available a program called XMITB64 written by Mark Feldman which does the Base
64 conversion. It can be downloaded from from Lionel Dyck's OS/390 freeware page in file name
XMITB64. There are instructions to get the source code and executable in this ZIP file (which
contains an XMIT MVS file). To use this, change the jobstream above to use this batch step for the
Base 64 encoding:
//*
//** Encode the ZIP file using the ENBASE64 Rexx exec
//*
//B64 EXEC PGM=XMITB64
//STEPLIB DD DISP=SHR,DSN=load.library.with.XMITB64 <-Modify!
//*
//ENCODIN DD DISP=SHR,DSN=ibmuser.A.ZIP
//ENCODOUT DD DSN=&&BASE64,
// DISP=(,PASS),UNIT=SYSDA,
// DCB=(LRECL=80,BLKSIZE=8800,RECFM=FB),
// SPACE=(CYL,(5,0),RLSE)
//SYSOUT DD SYSOUT=*
//SYSUDUMP DD SYSOUT=*
Submit and verify.
Sending mail to MS-Exchange servers with fonts and
colors
Background
Microsoft Exchange clients (Exchange, Outlook, Outlook Express, etc.) use a proprietary formatting
scheme called MS-TNET, Transport Neutral Encapsulation Format. They have not released full specs
on it. The following SMTP e-mail shows a sample note sent from a MS-Exchange server to a non-MS
Exchange host with "Rich-Text" format turned on the mail client:

From: "Alcock, David"

To: 'VMDAVE'
Subject: test message in ms ex rtf
X-Mailer: Microsoft Exchange Server Internet Mail Connector Version
4.0.995.52
Mime-Version: 1.0
Content-Type: multipart/mixed; boundary="----
=_NextPart_000_01BD3616.D408F860"

This message is in MIME format. Since your mail reader does not understand
this format, some or all of this message may not be legible.

------ =_NextPart_000_01BD3616.D408F860
Content-Type: text/plain; charset="us-ascii"
Content-Transfer-Encoding: 7bit

THIS IS IN RED (ARIAL)

THIS IS IN BLUE (COURIER)

Plain Courier text

------ =_NextPart_000_01BD3616.D408F860
Content-Type: application/ms-tnef
Content-Transfer-Encoding: base64

eJ8+IgwRAQaQCAAEAAAAAAABAAEAAQeQBgAIAAAA5AQAAAAAAADoAAEIgAcAGAAAAElQTS5NaWNy
lKHAKX8QG6WHCAArKiUXHgA9AAEAAAABAAAAAAAAAAsAKQAAAAAACwAjAAAAAAACAX8AAQAAADwA
...many data lines deleted...
AAA8Yz1VUyVhPV8lcD1DU1clbD1EQVMxMTMtOTgwMjEwMTcyNzA5Wi01Njk1QGRhczExMy5jc3cu
Y29tPgAiVA==

------ =_NextPart_000_01BD3616.D408F860--
Now What?
Since we would rather not reverse-engineer the MS-TNEF MIME type, we do have an alternative:
using HTML (the standard used in web pages). See the next section.
Note: MS-Exchange 5.0 and higher servers support HTML MIME e-mail attachments.
MS-Exchange, MS-TNEF and RTF links:

• Michael Santovec's Decoding Internet Attachments

• Search Microsoft's Knowledge database for these entries.
o XCLN: Sending Messages In Rich-Text Format
o XFOR: Preventing WINMAIL.DAT Sent to Internet Users
• See article "Using Exchange Server with SMTP and POP3", June 1998 page 177 in Windows
NT magazine. This article is not online, you will need to read it on dead trees.

Sending mail from MVS with fonts and colors using HTML
Many email clients such as Netscape and MS Outlook Express can properly handle HTML (Hyper Text
Markup Langauge) formated email. HTML is the language used in web pages. Here is an example of
a jobstream that sends a SMTP note with a HTML MIME extension:

//SENDNOTE EXEC PGM=IEBGENER

//SYSIN DD DUMMY
//SYSPRINT DD SYSOUT=*
//SYSUT2 DD SYSOUT=(B,SMTP)
//SYSUT1 DD *
helo MVSHOST
mail from:
rcpt to:
data
From: MVSUser@MVSHost.xyz.com
To: unixuser@pop3.xyz.com
Subject: Test message from MVS using SMTP (with
HTML MIME)
MIME-Version: 1.0
Content-type: multipart/mixed;
boundary="simple boundary"

You have received mail whose body is in the HTML

Format.
--simple boundary
Content-type: text/html

This is Courier font in blue

This is the Arial font in red

--simple boundary--
/*

See the text following the first IEBGENER example for the things you will need to change.

The note above would look something like this:

From: MVSUser@MVSHost.xyz.com
To: unixuser@pop3.xyz.com
Subject: Test message from MVS using SMTP (with HTML MIME)

This is Courier font in blue

This is the Arial font in red

sendmail on z/OS
IBM has made available sendmail on z/OS although I have no experience with using it.
PGP on OS/390
Likewise there are freeware and commercial implementations of PGP that run on z/OS but I have no
experience using them.
TSO XMIT/RECEIVE
IBM provides a couple of commands on TSO that allow you to send notes between MVS and VM
systems called the TSO TRANSMIT (XMIT) and RECEIVE commands. I have a small write up on XMIT
on my Terms page.
If you use XMIT and RECEIVE a lot for email, you will want to get a copy of Lionel Dycks TSOEMAIL
application. It is available on his OS/390 freeware page. This is a ISPF application that uses XMIT and
RECEIVE and puts your notes in a nice table display.
Simple XMIT/RECEIVE instructions:

• To send an e-mail from MVS to another MVS or VM system, use this command:

XMIT njenode.userid

A full-screen will pop up with an input area to type in an e-mail.

• To receive mail sent to you from another system (or another user on your system), use this
TSO command:

RECEIVE

Pretty simple stuff...

XMIT links and technical information:

• The XMIT file format is explained in TSO/E Customization manual. At the TSO/E 2.5 level,
the manual number is SC28-1872. See the section called "Format of Transmitted Data".

• See my Un-XMIT information page.

MVS MAIL FAQ
I can't get the IEBGENER SMTP job to send mail. Can you help me?

You should ensure that the SMTP task is correctly configured and operational at your site. If
IBM's SMTPNOTE command doesn't send mail, the IEBGENER examples probably won't
work either.

How do I direct all SMTP mail processed by the IBM MVS SMTP server to one mail server?

This is taken verbatim from Lionel Dyck's XMITIP package (available on his OS/390
freeware page):

1. Find the dataset pointed to by the SYSTCPD DD in the TCPIP started task JCL and
make a copy for use in the SMTP started task JCL.

2. In the copy of (1) comment out the NSINTERADDR statements. These statements
are used to define the domain name servers that will be used to resolve host
names.

3. In the SMTP CONFIG data add the IPMAILERADDRESS statement. The syntax is
IPMAILERADDRESS xx.xx.xx.xx where the xx.xx.xx.xx is the numeric IP address of
the target mail server.

SMTP will now forward all mail for which it is unable to resolve the target host name to the
server defined in the IPMAILERADDRESS.

How do I see what mail is being processed by the SMTP task?

Turn on the DEBUG option in the SMTP config file

How do I see the queues being processed by the SMTP task?

One way is to TELNET into your MVS system to port 25. In Windows 9x, type in "TELNET
mvshost 25" in your MS/DOS prompt and type in QUEU to get:
220 mvshost.mydomain running IBM MVS SMTP CS V2R6 on Sat, 21 Oct 00 17:00:52
CDT
250-Queues on mvshost.mydomain at 17:00:59 CDT on 10/21/00
250-Spool Queue: Empty
250-Undeliverable Queue: Empty
250-Resolution Queues:
250-Resolver Process Queue: Empty
250-Resolver Send Queue: Empty
250-Resolver Wait Queue: Empty
250-Resolver Retry Queue: Empty
250-Resolver Completed Queue: Empty
250-Resolver Error Pending Queue: Empty
250 OK

Then type QUIT to end.

Note: I've personally never seen any useful information here but that's how you are
suppose to do it.

How do I send mail to VM with TSO's XMIT command with valid subject lines?

Older OfficeVision versions don't process the "Subject:" lines for e-mail received from MVS
systems sent with IBM's XMIT command. OfficeVision requires that email send in NETDATA
format (used by XMIT) have a trailer record that has the Subject information.
Lionel Dyck has written a rexx exec called XMITVM (available on his OS/390 freeware page)
which will send a TSO XMIT file to VM with the proper trailer record that OfficeVision and
PROFs needs so it will display a subject line in the mail list.
Later versions of OfficeVision may include support to NETDATA e-mail and capture the
subject line from the body of the e-mail and not the trailing subject line.