NAME

Qmail::Envelope - Perl module modifying qmail envelope strings.

SYNOPSIS

  use Qmail::Envelope;

  ## When you have received the envelope from qmail-smtpd
  my $E = Qmail::Envelope->new (data => $Envelope);

  ## or if you want to create one on the fly ...
  my $E = Qmail::Envelope->new();

  ## add a recipient
  $E->add_recip('foo@bar.com');

  ## remove a recipient
  $E->remove_recip('foo@ack.com');

  ## remove all recipients for a specific domain
  $E->remove_recips_for_host('quux.com');

  ## clear the entire recipient list
  $E->remove_all_recips;

  ## get ref to an array containing the list of hosts in the envelope
  my $host_list = $E->rcpt_hosts;

  ## get envelope sender
  my $sender = $E->sender;
  
  ## set envelope sender 
  $E->sender('blarch@chunk.com');

  ## get the total number of recipients in the envelope.
  ## duplicates are counted.
  my $number_of_recips = $E->total_recips;

  ## get the total numbers of recips for a specific host
  my $number_of_recips = $E->total_recips_for_host('frobnicate.com');

  ## remove duplicate recipient entries in the envelope
  $E->remove_duplicate_recips;

  ## pretty print the envelope
  print $E->as_string;

  ## complete formatted envelope, with terminating null bytes and all.
  my $envelope = $E->gen;

DESCRIPTION

This module takes a qmail envelope, and allows you perform operations on it. You can also create qmail envelopes from scratch. A quick background: qmail-smtpd hands all mail messages it receives to the mail queuer program, qmail-queue. qmail-queue gets the message (headers and body) from qmail-smtpd on file descriptor 1, and the envelope on file descriptor 2. Yeah, I thought it was weird at first too.

Anyway, the envelope is a string which contains the sender and all of the recipients of a mail message. This envelope may or may not match the headers of the mail message (think cc and bcc). The envelope tells qmail-queue where the message is from, and where it is going to.

This module my help you if you have decided to insert a perl script in between qmail-smtpd and qmail-queue. There is an interesting open source program called qmail-scanner which (in its documentation) explains how to accomplish this this neat trick.

I hope this module helps someone out there. I've been using it in a production environment for some time now, and it seems stable.

EXPORT

None by default.

SEE ALSO

Useful to me was qmail-scanner program, located at: http://qmail-scanner.sourceforge.net/

Also helpful were the man pages for qmail-smtpd, qmail-queue, and envelopes. They all come with the qmail mail server source.

You can see the other (few) things I've written at http://www.avitable.org/software

AUTHOR

root, <mja-perl@escapement.net>

COPYRIGHT AND LICENSE

Copyright 2004 by Matt J. Avitable

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.