PREV NEXT INDEX


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
PREV NEXT INDEX