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.

on_disconnect: 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/

COPYRIGHT

POD ERRORS

Hey! The above document had some coding errors, which are explained below:

Around line 368:: '=item' outside of any '=over'
Around line 400:: You forgot a '=back' before '=head1'