> ## 8. SMTP Mail Client

> SMTP (Simple Mail Transfer Protocol) is one of the most common ways of sending e-mail. SMTP is a simple text conversation across a TCP/IP connection. The SMTP server usually resides on TCP port 25 waiting for clients to connect.

> Sending mail with the `SMTP.LIB` client library is a four-step process. First, build your e-mail message, then call `smtp_sendmail()`. Next, repetitively call `smtp_mailtick()` while it is returning `SMTP_PENDING`. Finally, call `smtp_status()` to determine if the mail was sent successfully. There is a sample program in Section 8.4 that outlines how to send a simple mail message.

> ### 8.1 Sample Conversation

> The following is a typical listing of mail from the controller (me@somewhere.com) to someone@somewhereelse.com. The mail server that the controller is talking to is mail.somehost.com. The lines that begin with a numeric value are coming from the mail server. The other lines were sent by the controller. More information on the exact specification of SMTP and the meanings of the commands and responses can be found in RFC821 at `http://www.ietf.org`.

>     220 mail.somehost.com ESMTP Service (WorldMail 1.3.122) ready
>     HELO 10.10.6.100

>     250 mail.somewhere.com
>     MAIL FROM: <me@somewhere.com>

>     250 MAIL FROM:<me@somewhere.com> OK
>     RCPT TO: <someone@somewhereelse.com>

>     250 RCPT TO:<someone@somewhereelse.com> OK
>     DATA

>     354 Start mail input; end with <CRLF>.<CRLF>
>     From: <me@somewhere.com>
>     To: <someone@somewhereelse.com>
>     Subject: test mail

>     test mail
>     .

>     250 Mail accepted
>     QUIT

>     221 mail.somehost.com QUIT

> You can see a listing of the conversation between your controller and the mail server by defining the `SMTP_DEBUG` macro at the top of your program.

> Note that there must be a blank line after the line "Subject: test mail".

> ### 8.2 Configuration

> The SMTP client is configured by using compiler macros.

> #### SMTP_DEBUG

> This macro tells the SMTP code to log events to the STDIO window in Dynamic C. This provides a convenient way of troubleshooting an e-mail problem.

> #### SMTP_DOMAIN

> This macro defines the text to be sent with the `HELO` client command. Many mail servers ignore the information supplied with the `HELO`, but some e-mail servers require the fully qualified name in this field (i.e., somemachine.somedomain.com). If you have problems with e-mail being rejected by the server, turn on `SMTP_DEBUG`. If it is giving an error message after the `HELO` line, talk to the administer of the machine for the appropriate value to place in `SMTP_DOMAIN`. If you do not define this macro, it will default to `MY_IP_ADDRESS`.

>     #define SMTP_DOMAIN "somemachine.somedomain.com"

> #### SMTP_SERVER

> This macro defines the mail server that will relay the controller's mail. This server must be configured to relay mail for your controller. You can either place a fully qualified domain name or an IP address in this field.

>     #define SMTP_SERVER "mail.mydomain.com"

> or

>     #define SMTP_SERVER "10.10.6.19"

> #### SMTP_TIMEOUT

> This macro tells the SMTP code how long in seconds to try to send the e-mail before timing out. It defaults to 20 seconds.

>     #define SMTP_TIMEOUT 10

> ### 8.3 Functions

> ## smtp_sendmail

>     void smtp_sendmail(char* to, char* from, char* subject, char* message);

> ### Description

> This function initializes the internal data structures with strings for the to e-mail address, the from e-mail address, the subject, and the body of the message. You should not modify these strings until `smtp_mailtick` no longer returns `SMTP_PENDING`.

> ### Parameters

> #### to

> String containing the e-mail address of the destination.

> #### from

> String containing the e-mail address of the source.

> #### subject

> String containing the subject of the message.

> #### message

> String containing the message. (This string must NOT contain the byte sequence "\r\n.\r\n" (CRLF.CRLF), as this is used to mark the end of the e-mail, and will be appended to the e-mail automatically.)

> ### Return value

> None

> ### Library

> SMTP.LIB

> ## smtp_sendmailxmem

>     void smtp_sendmailxmem(char* to, char* from, char* subject, long message, long messagelen);

> ### Description

> This function initializes the internal data structures with strings for the to e-mail address, the from e-mail address, the subject, and the body of the message. You should not modify these strings until `smtp_mailtick` no longer returns `SMTP_PENDING`.

> ### Parameters

> #### to

> String containing the e-mail address of the destination.

> #### from

> String containing the e-mail address of the source.

> #### subject

> String containing the subject of the message.

> #### message

> Physical address in xmem containing the message. (The message must NOT contain the byte sequence "\r\n.\r\n" (CRLF.CRLF), as this is used to mark the end of the e-mail, and will be appended to the e-mail automatically.)

> #### messagelen

> Length of the message in xmem.

> ### Return value

> None

> ### Library

> `SMTP.LIB`

> ## smtp_mailtick

>     int smtp_mailtick(void);

> ### Description

> Repetitively call this function until e-mail is completely sent. For a small message, this function will need to be called about 20 times to send the message. The number of times will vary depending on the latency of you connection to the mail server and the size of your message.

> ### Return value

> `SMTP_SUCCESS` - e-mail sent.
> `SMTP_PENDING` - e-mail not sent yet call `smtp_mailtick` again.
> `SMTP_TIME` - e-mail not sent within `SMTP_TIMEOUT` seconds.
> `SMTP_UNEXPECTED` - received an invalid response from SMTP server.

> ### Library

> SMTP.LIB

> ## smtp_status

>     int smtp_status(void);

> ### Description

> Return the status of the last e-mail processed.

> ### Return value

> `SMTP_SUCCESS` - e-mail sent.
> `SMTP_PENDING` - e-mail not sent yet call smtp_mailtick again.
> `SMTP_TIME` - e-mail not sent within `SMTP_TIMEOUT` seconds.
> `SMTP_UNEXPECTED` - received an invalid response from SMTP server.

> ### Library

> SMTP.LIB

> ### 8.4 Sample Sending of an E-mail

> This program, `smtp.c`, uses the SMTP library to send an e-mail. For an example of using `smtp_sendmailxmem()`, see the sample program `samples\tcpip\smtp\smtpxmem.c`.

> #### Program Name: /samples/tcpip/smtp/smtp.c

>     /* Change these macros to the appropriate values or change
>      * the smtp_sendmail(...) call in main() to reference your values.
>      */

>     #define FROM     "myaddress@mydomain.com"
>     #define TO       "myaddress@mydomain.com"
>     #define SUBJECT  "test mail"
>     #define BODY     "You've got mail!"

>     /* Change these values to your network settings */
>     #define MY_IP_ADDRESS "10.10.6.100"
>     #define MY_NETMASK    "255.255.255.0"
>     #define MY_GATEWAY    "10.10.6.19"

>     /* SMTP_SERVER tells DCRTCP where your mail server is. This
>      * value can be the name or the IP address. */

>     #define SMTP_SERVER "mymailserver.mydomain.com"

>     //#define SMTP_DOMAIN "mycontroller.mydomain.com"

>     //#define SMTP_DEBUG

>     #memmap xmem
>     #use dcrtcp.lib
>     #use smtp.lib

>     main() {
>        sock_init();

>        smtp_sendmail(FROM, TO, SUBJECT, BODY);

>        while(smtp_mailtick()==SMTP_PENDING)
>           continue;

>        if(smtp_status()==SMTP_SUCCESS)
>           printf("Message sent\n");
>        else
>           printf("Error sending message\n");
>     }

Z-World http://www.zworld.com Voice: 530.757.3737 Fax: 530.757.3792 or 530.753.5141 sales@zworld.com