14. Sending and Receiving Email

14. Sending and Receiving Email

Introduction

Miva Script provides tags that can send and receive email. SMTP is used to send mail from any valid mail server, and Miva Script documents can receive email by becoming POP3 clients.

Sending Mail

<MvSMTP>

<MvSMTP
TO="to_address1,to_address2,..."
SUBJECT="expression"
CC="cc_address1,cc_address2,..."
MAILHOST="mailhost"
FROM="from_address">
[optional headers]
[blank line]
... message body (text/tags)...
</MvSMTP>

Send mail, using SMTP, to the to_address1, to_address2, ... email addresses. Required are: at least one TO value, a MAILHOST value consisting of the domain name or IP address of a host that understands SMTP, and the sender's email address (FROM). Optionally, one or more CC ("carbon copy") addresses and a SUBJECT line can be specified. The message body appears between the <MvSMTP> and </MvSMTP> tags.

The following is an example of sending email with <MvSMTP>:

<MvSMTP
TO="les@some_isp.com,janice@some_isp.com"
FROM="royc@my_isp.com"
MAILHOST="my_isp.com"
CC="leanne@some_isp.com,toyah@some_isp.com"
SUBJECT="Weatherfield Alien Abduction Society">

Friends: the next meeting of the Society will be
on April 16, 1998.
</MvSMTP>

where:

A value for TO is mandatory and indicates that the mail is outgoing. TO can contain a single email address or a comma-separated list of email addresses.

FROM is mandatory and contains the email address of the person sending the message.

MAILHOST is mandatory and must contain the domain name or IP address of your mail host (a host that understands SMTP). If you don't know this value, check with your ISP or system administrator.

SUBJECT is optional and can contain text that will be used as the message's Subject line. If no subject is specified, then the text 'no subject' is used as the default subject.

CC is optional and can contain a single email address or a comma-separated list of email addresses.

Mail headers, if present, must be placed on the line directly after the <MvSMTP> tag. Whether or not there are mail headers, the line before the message contents must be left blank.

Enter the text of your message between the blank line and the </MvSMTP> tag. The message can also be generated by other Miva Script tags between the <MvSMTP> and </MvSMTP> tags; for example, an <MvCALL> tag could be used to obtain a text file.

Address Formats

Most SMTP hosts are very flexible as to the formats the allow for e-mail addresses (as specified with FROM, TO, and CC). For example, you may wish to specify "real names":

<MvSMTP TO="Roy Cropper <royc@my_isp.com>" ...>

If you include a name with the address, surround the address with '<' and '>', as in the example. You must not put a comma in the name.

Some servers do not allow this form of address, so before you "go live" with a script you should test this format on the server you intend to use. By contrast, some SMTP servers require that addresses be surrounded by '<' and '>'. In all cases, you should perform tests with your server, and ensure that the values you provide for FROM, TO, and CC meet your server's requirements.

Mail Headers

In addition to ordinary content, mail messages can contain mail headers: for example, Reply-To, Return-Path, and Sender. Mail headers, if present, must be placed on the line directly after the <MvSMTP> tag. Whether or not there are mail headers, the line before the message contents must be left blank. For example:

<MvSMTP
TO="les@some_isp.com,janice@some_isp.com"
FROM="royc@my_isp.com"
MAILHOST="my_isp.com"
CC="leanne@some_isp.com,toyah@some_isp.com"
SUBJECT="Weatherfield Alien Abduction Society">
Reply-To: roy.cropper@my_isp.co.uk

Friends: the next meeting of the Society will be
on April 16, 1998.
</MvSMTP>

This adds the Reply-To header to the message.

To understand how <MvSMTP> handles headers, you need to understand something about how mail messages are handled generally. The basic situation is that a user uses a program called a mail client to create a mail message, and send it to another program called a mail server, which communicates with the network. Because there are many different implementations of mail clients and mail servers, the specific tasks that each one carries out will differ from program to program. In particular, some mail clients and some mail servers will interpret various mail headers, and some won't. Miva, acting as a mail client when it encounters an <MvSMTP> tag, interprets only the data passed to it with the TO, FROM, CC, and SUBJECT attributes, and generates the appropriate headers and SMTP codes for this data. Any other headers are passed to the mail server unchanged. They become the responsibility of the server; how they are processed (if at all) depends on the server configuration. For this reason, headers such as Bcc, which require extra processing, are not guaranteed to have the expected effect. You should test with the specified MAILHOST any such headers that you intend to use.

Some useful references are: RFC 822 (http://www.sendmail.org/rfc/0822.html), the Standard for Internet Text Messages, for more information on mail headers; RFC 821 (http://www.sendmail.org/rfc/0821.html) for information on SMTP; and RFC 1123 (http://www.sendmail.org/rfc/1123.html) for information on Internet hosting in general.

Reading Mail

<MvPOP>

<MvPOP> creates a loop that logs into the POP3 mail server named host, using the login_name and password login information, and retrieves all incoming mail messages, one message at a time. Messages are stored on your local system (that is, the system running Miva, not necessarily the system running the POP3 server) under unique filenames, in the directory specified with DIRECTORY. The host, login name, password, and storage directory are all required. When a message is retrieved, information about the message is stored in the special variables messagebody, messagesubject, messagereplyto, messagesender, and messagedate. This information can then be processed inside the loop. If an <MvPOPDELETE> (optional) is executed, the current message is deleted from the server. If an <MvPOPSTOP> (optional) is executed, the <MvPOP> loop terminates. <MvPOPDELETE> and <MvPOPSTOP> are empty tags.

Syntax:

<MvPOP
MAILHOST="host"
LOGIN="login_name"
PASSWORD="password"
DIRECTORY="directory">
...code...
<MvPOPDELETE>
...code...
<MvPOPSTOP>
...code...
</MvPOP>
The following is an example of reading mail with <MvPOP>:
<MvPOP
MAILHOST="mail.my_isp.com"
LOGIN="my_userid"
PASSWORD="pa55w0rd"
DIRECTORY="mymail">
You received mail from: <MvEVAL EXPR="{messagesender}">. 
This mail is about: <MvEVAL EXPR="{messagesubject}">. 
This mail was sent on: <MvEVAL EXPR="{messagedate}">. 
I stored this mail in the file: <MvEVAL EXPR="{messagebody}">. 
You can reply to: <MvEVAL EXPR="{messagereplyto}">.

</MvPOP>

This code reads incoming email messages belonging to the user my_userid, who has the password pa55w0rd, on the mail server mail.my_isp.com; these messages are stored in a directory called mymail.

Note: The storage directory should be specified as a directory relative to the data directory of the owner of the active document if Miva Merchant Empresa is running in server-safe (multi-user) mode; it can be a relative or absolute path if Miva Merchant Empresa is running in standard mode.

When <MvPOP> retrieves an email message, it stores information about the message in several special variables:

messagesubject

The 'Subject:' line of the incoming message.

messagedate

The 'Date:' line of the message.

messagesender

The 'From:' line (sender) of the message. Do not use this value for replying to a message; instead, use the value of messagereplyto.

messagereplyto

The 'Reply-To:' line (the address to which replies should be sent). If the incoming message does not have 'Reply-To' in its header, then the 'From:' line is used for this value.

messagebody

A guaranteed unique file name in which the message body has been saved.

Some or all of the first four values in the list may be unavailable if the message header is missing or truncated.

Some sample output would be:

You received mail from: Walter Mitty.
This mail is about: My latest adventures.
This mail was received on: Tue, 10 Mar 2000 13:50:10 -0500 (EST).
I stored this mail in the file: mymail/MIVA_POP.a06431.
You can reply to: Walter Mitty.

If there is more than one incoming message, <MvPOP> will iterate through them and print these fields for each message.

Deleting an Email Message

By default, <MvPOP> does not remove email messages from the POP3 server. If you want to remove a message, you need to execute an <MvPOPDELETE> tag inside the <MvPOP> loop. This deletes the current email message on the server. The message will still be processed by the application in this iteration of the <MvPOP> loop.

Make sure the temp files are deleted. Since some servers do not remove their temp files, make sure you delete the temp files, where present.