Libsmtp - A simple SMTP library (C)opyright 2001-2002 Kristian Van Der Vliet

API

The API for Libsmtp is very simple, with only four functions available.  They
allow you to connect to a server, send a mail, and disconnect from the server.

The functions as defined in inc/libsmtp.h are as follows:

int smtp_connect(const char* zServer, int nPort);
int smtp_sendmail(const char* zTo, const char* zFrom, const char* zBody);
int smtp_disconnect(void);
int smtp_set_timeout(unsigned long nTimeout);

A simple example is provided at the end of this document.

smtp_connect()

The smtp_connect() function attempts to connect to the given SMTP server on the
port requested.  For example, to attempt a connection to the server
"mail.isp.com" on the default SMTP port (25), you would use:

	smtp_connect("mail.isp.com",25);

smtp_connect() will return 0 on success or one of the following error messages
if a connection to the server could not be made.

	-SMTP_UNKNOWN_SERVER	- The server could not be found (I.E the DNS lookup 
				failed)
	-SMTP_CONNECT_FAILED	- Libsmtp could not connect to the server.
				It could be that the port you have requested is incorrect.
	-SMTP_TIMED_OUT		- The remote server did not respond before the set 
				time allowed (See smtp_set_timeout() for more 	
				information)

smtp_sendmail()

The smtp_sendmail() function will attempt to send an (Already formated) mail to
the user or users requested.  As an example, if you wanted to send a mail to
the users "fred@foo.com" and "jane@baz.org", and you are "frodo@bagend.com" you
could use:

	smtp_sendmail("fred@foo.com, jane@baz.org","frodo@bagend.com",&message);

smtp_sendmail() will return 0 on success or one of the following error messages
if the mail could not be sent.

	-SMTP_INVALID_FROM	- The "From" address you are attempting to use is 
				invalid in some way.
	-SMTP_INVALID_TO		- The "To" address(s) you are attempting to use are 
				invalid in some way.
	-SMTP_SEND_FAILED	- The server would not allow you to send the mail, 
				most likely due to an error at the remote server.
	-SMTP_TIMED_OUT		- The remote server did not respond before the set 
				time allowed (See smtp_set_timeout() for more 	
				information)

Note: smtp_sendmail() assumes that you have already formated your mail
according to the relevant RFC's, I.E you have created the basic headers, your
message does not contain any invalid characters, and you have done any encoding
(E.g Quoted Printable, Base64 etc) on the message yourself.  In practice for
smaller messages this is not difficult.  smtp_sendmail() will not perform any
formatting or validity checking on the message you are trying to send.

smtp_disconnect()

The smtp_disconnect() function will attempt to disconnect cleanly from the
remote server, and closes connection to the server.  There are no arguments to
smtp_disconnect(), and the function will either return 0 on success, or
-SMTP_DISCONNECT_FAILED if libsmtp could not disconnect properly from the
server.  In either instance, the connection to the server will be closed.

smtp_set_timeout()

By default, libsmtp will timeout and return an error if it does receive a
response from the server after 30 seconds.  You can change this timeout value
with the smtp_set_timeout() function.  There are no upper or lower limits on
the timeout value you can set, but a timeout value of 0 is "No timeout", which
means that libsmtp will sit and wait indefinatly for the server to respond.
Conversely, a very large timeout value will cause libsmtp to seem to be waiting
forever for the server to respond!  You should be careful about the values you
use.  Something between 20 and 120 seconds is probably a good value to use.

Example Usage

Below is a very simple example for using libsmtp.  The code attempts to connect
to the (Fictional) server "mail.isp.com" on the default SMTP port, and sends a
simple "Hello World!" message to two (Fictional) users, "fred@foo.com" and
"jane@baz.org"

--Begin Example--

#include "inc/libsmtp.h"
#include "inc/libsmtp_errors.h"

#include <stdio.h>

int main(void);

int main(void)
{
	int nReturnCode=0;	/* Return code from libsmtp */
	char message[]="From: frodo@bagend.com\r\nTo: fred@foo.com, 
jane@baz.org\r\nSubject: Libsmtp example\r\n\r\nThis is a message to show libsmtp in 
action\r\n";

	/* Obviously you can build your message dynamically.  This message does not 
include all the headers required by RFC2822, only the bare minimum */

	printf("Connecting to server\n");
	if(smtp_connect("mail.isp.com",25)<0)
	{
		printf("Failed to connect to server!\n");
		return(1);
	}

	printf("Connected\nSending mail\n");

	if(smtp_sendmail("fred@foo.com, jane@baz.org","frodo@bagend.com",&message)<0)
	{
		printf("Failed to send mail\n");
		/* Attempt to disconnect from the server */
		smtp_disconnect();

		return(1);
	}

	printf("Mail sent successfully\nDisconnecting\n");

	smtp_disconnect();

	printf("All done!\n");

	return(0);
}

--End Example--