POE::Component::Server::SimpleSMTP is a POE component that provides an ease to use, but fully extensible SMTP mail server, that is reasonably compliant with RFC 2821 http://www.faqs.org/rfcs/rfc2821.html.

In its simplest form it provides SMTP services, accepting mail from clients and either relaying the mail to a smart host for further delivery or delivering the mail itself by querying DNS MX records.

One may also disable simple functionality and implement one's own SMTP handling and mail queuing. This can be done via a POE state interface or via POE::Component::Pluggable plugins.

'alias', set an alias on the component;
'address', bind the listening socket to a particular address;
'port', listen on a particular port, default is 25;
'options', a hashref of POE::Session options;
'hostname', the name that the server will identify as in 'EHLO';
'version', change the version string reported in 220 responses;
'relay', specify a 'smart host' to send received mail to, default is
to deliver direct after determining MX records;
'relay_auth', ESMTP Authentication to use, currently only PLAIN is supported, which is the default;
'relay_user', the username required for authenticated relay;
'relay_pass', the password required for authenticated relay;
'time_out', alter the timeout period when sending emails, default 300 seconds;
'maxrelay', maximum number of concurrent outgoing emails, defaults to 5;
'domains', an arrayref of domain/hostnames that we will accept mail for;
'origin', set to a true value to enable the stripping of Received headers;

These optional arguments can be used to enable your own SMTP handling:

'simple', set this to a false value and the component will no
longer handle SMTP processing;
'handle_connects', set this to a false value to stop the component sending
220 responses on client connections;

In simple mode one may also specify recipient handlers. These are regular expressions that are applied to each recipient of a recieved email. If a recipient matches the handler, it is removed from the process queue and dispatched instead to indicated session/event combo.

'handlers', an arrayref containing hashrefs. Each hashref should contain the keys:
'match', a regexp to apply;
'session', The session to send the email to;
'event', The event to trigger;

You may also enable DNSBL lookups of connecting clients with the following options:

'dnsbl_enable', set to a true value to enable DNSBL support;
'dnsbl', set to a DNSBL to query, default is zen.spamhaus.org;

DNSBL support uses POE::Component::Client::DNSBL to make blacklist queries for each connecting client. If a client is found in the blacklist, any further interaction with the client is denied.

You may also enable sender verification, this does a simple MX DNS lookup on the domain of the email sender. If there is no MX domain record (ie. an NXDOMAIN) then a 550 is issued. In the case of a SERVFAIL, a 451 is issued. In both cases the email transaction is cancelled.

'sender_verify', set to a true value to enable sender verification;

See OUTPUT EVENTS below for information on what a handler event contains.

Takes one argument a valid client ID. Switches the client connection to data mode for receiving an mail message. This should be done in response to a valid DATA command from a client if you are doing your own SMTP handling.

You will receive an 'smtpd_data' event when the client has finished sending data. See below.

Optionally, you may supply a filehandle as a second argument. Any data received from the client will be written to the filehandle. You will receive an 'smtpd_data_fh' event when the client has finished sending data.

Takes one argument, a hashref with the following keys and values. Enqueues the item and requests that the mail queue be processed. Returns undef on failure or 1 on success.

'from', the email address of the sender (required);
'rcpt', an arrayref of the email recipients (required);
'msg', string representation of the email headers and body (required);
'ts', the unix time representation of the time the email was received (default is now);
'uid', the Message-ID (default is to generate one for you);

Takes N arguments: a list of event names which you don't want to receive. If you've previously done a 'register' for a particular event which you no longer care about, this event will tell the SMTPD to stop sending them to you. (If you haven't, it just ignores you. No big deal).

Generated if the component cannot either start a listener or there is a problem accepting client connections. ARG0 contains the name of the operation that failed. ARG1 and ARG2 hold numeric and string values for $!, respectively.

Generated for each SMTP command that a connected client sends to us. ARG0 is the client ID. ARG1 .. ARGn are any parameters that are sent with the command. Check the RFC http://www.faqs.org/rfcs/rfc2821.html for details.

If simple is true ( which is the default ), the component deals with client commands itself.

ARG0 will be the client ID;
ARG1 will be the response sent to the client, either a 220 or 554;
ARG2 will be a hashref with the following keys:
'response', the status returned by the DNSBL, it will be NXDOMAIN if the address given was okay;
'reason', if an address is blacklisted, this may contain the reason;
'error', if something goes wrong with the DNS lookup the error string will be contained here;
'dnsbl', the DNSBL that was used for this request;

ARG0 is the client ID;
ARG1 is the mail from address;
ARG2 is an arrayref of recipients;
ARG3 is the email unique idenitifer;
ARG4 is the number of lines of the message;
ARG5 is the subject line of the message, if applicable

Generated whenever a mail message is unsuccessfully delivered. This can be for a variety of reasons. The poco will attempt to resend the message on non-fatal errors ( such as an explicit denial of delivery by the SMTP peer ), for up to 4 days.

ARG0 is the email unique identifier;
ARG1 is a hashref as returned by POE::Component::Client::SMTP via 'SMTP_Failure'

Handler events are generated whenever a recipient matches a given regexp. ARG0 will contain a hashref representing the email item with the following keys:

'uid', the Message-ID;
'from', the email address of the sender;
'rcpt', an arrayref of the email recipients;
'msg', string representation of the email headers and body;
'ts', the unix time representation of the time the email was received;

This means the event will continue to be processed by remaining plugins but it will not be sent to any sessions that registered for it. This means nothing will be sent out on the wire if it was an SMTPC event, beware!