NAME

POE::Component::Server::SMTP - SMTP Protocol Implementation

SYNOPSIS

  use POE;
  use POE::Component::Server::SMTP;

  POE::Component::Server::SMTP->spawn(
    Port => 2525,
  	InlineStates => {
  		HELO => \&smtp_helo,
  		QUIT => \&smtp_quit,
  	},
  );

  sub smtp_helo {
    my ($heap) = $_[HEAP];
    my $client = $heap->{client};

    $client->put( SMTP_OK, 'Welcome.' );
  }

  sub smtp_quit {
    my ($heap) = $_[HEAP];
    my $client = $heap->{client};

    $client->put( SMTP_QUIT, 'Good bye!' );
    $heap->{shutdown_now} = 1;
  }

  $poe_kernel->run;
  exit 0;

DESCRIPTION

POE::Component::Server::TCP implements the SMTP protocol for the server. I won't lie, this is very low level. If you want to support any command other than HELO and QUIT, you'll have to implement it yourself, and define it in your InlineStates, PackageStates, or ObjectStates.

This module uses POE::Session::MultiDispatch to allow for "Plugins" using PackageStates and ObjectStates.

Also, as of this release, POE version 0.24 is out. This module relies on a CVS version of POE.

Constants

This module exports a bunch of constants by default.

	SMTP_SYTEM_STATUS SMTP_SYSTEM_HELP SMTP_SERVICE_READY SMTP_QUIT
	SMTP_OK SMTP_WILL_FORWARD SMTP_CANNOT_VRFY_USER

	SMTP_START_MAIL_INPUT

	SMTP_NOT_AVAILABLE SMTP_SERVICE_UNAVAILABLE
	SMTP_LOCAL_ERROR SMTP_NO_STORAGE

	SMTP_SYNTAX_ERROR SMTP_ARG_SYNTAX_ERROR SMTP_NOT_IMPLEMENTED
	SMTP_BAD_SEQUENCE SMTP_ARG_NOT_IMPLEMENTED SMTP_UNAVAILABLE
	SMTP_USER_NOT_LOCAL SMTP_QUOTA_LIMIT SMTP_MAILBOX_ERROR
	SMTP_NO_SERVICE SMTP_TRANSACTION_FAILED

If you don't know what these mean, see the source.

spawn( %args )

Create a new instance of the SMTP server. The argument list follows.

Alias: The alias name for this session.
Address: The address to bind to. If you don't do this you run the risk of becomming a relay.
Hostname: The host name to use when identifying the SMTP server.
Port: The port to listen and accept connections on.
PackageStates: Passed directly to POE::Session::MultiDispatch.
ObjectStates: Passed directly to POE::Session::MultiDispatch.
InlineStates: Passed directly to POE::Session::MultiDispatch.

Events

There are only three builtin events. This way, the default POE::Component::Server::SMTP distribution is completley secure. Unless otherwise noted, event names corrispond to the uppercase version of the verb supplied from the client during an SMTP connection (HELO, VRFY, RCPT).

Any input supplied after the command verb will be available to the event handler in $_[ARG1], the command name itself is available in $_[ARG0].

send_banner

This event is triggered when a client connects and it's time to send a banner. This can be supplied in your own send_banner event in your InlineStates.

HELO

This event is triggered when a client sends a HELO command. This can be supplied in your own HELO event in your InlineStates.

QUIT

This event is triggered when a client sends a QUIT command. This can be supplied in your own QUIT event in your InlineStates.

This event should always set $heap-{shutdown_now}> to a true value.

In the source of this module there are two example handlers for handling the DATA event. The DATA event is kind of tricky, so refer to the smtpd_DATA and smtpd_gotDATA subroutines in the source.

This event is called when the client disconnects. Specifically, when POE::Component::Server::TCP throws the ClientDisconnected state. You can't always rely on an SMTP client calling QUIT, so use this for garbage collection or handling an unexpected end of session.

Any event that it triggered from the client that the server doesn't know how to handle will be passed to the _default handler. This handler will return SMTP_NOT_IMPLEMENTED, unless you override it using InlineStates and do something else.

BUGS

No doubt.

It should be noted that this is extremley early code. After all, it relies on features of POE that haven't even been released. Anything could change!

See http://rt.cpan.org to report bugs.

Known Issues

The following is what I would consider known issues.

: The only way to override builtin event handlers is using InlineStates. The truth is that there probably shouldn't be any builtin handlers. They will probably go away soon.
: Documentation and Tests are lacking.
: There is no POE::Component::Client::SMTP yet, though that's really a TODO item.

AUTHOR

Casey West <casey@geeknest.com>

THANKS

Meng Wong, and http://pobox.com/