.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.28)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
.    if \nF \{
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Verp 3pm"
.TH Verp 3pm "2007-06-30" "perl v5.20.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Mail::Verp \- encodes and decodes Variable Envelope Return Paths (VERP) addresses.
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  use Mail::Verp;
\& 
\&  #Using class methods
\&
\&  #Change separator to something else
\&  Mail::Verp\->separator(\*(Aq+\*(Aq);
\&
\&  #Create a VERP envelope sender of an email to recipient@example.net.
\&  my $verp_email = Mail::Verp\->encode(\*(Aqsender@example.com\*(Aq, \*(Aqrecipient@example.net\*(Aq);
\&
\&  #If a bounce comes back, decode $verp_email to figure out
\&  #the original recipient of the bounced mail.
\&  my ($sender, $recipient) = Mail::Verp\->decode($verp_email);
\& 
\& 
\&  #Using instance methods
\&
\&  my $verp = Mail::Verp\->new(separator => \*(Aq+\*(Aq);
\&
\&  #Create a VERP envelope sender of an email to recipient@example.net.
\&  my $verp_email = $verp\->encode(\*(Aqsender@example.com\*(Aq, \*(Aqrecipient@example.net\*(Aq);
\&
\&  #Decode a bounce
\&  my ($sender, $recipient) = $verp\->decode($verp_email);
.Ve
.SH "ABSTRACT"
.IX Header "ABSTRACT"
Mail::Verp encodes and decodes Variable Envelope Return Paths (\s-1VERP\s0) email addresses.
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Mail::Verp encodes the address of an email recipient into the envelope
sender address so that a bounce can be more easily handled even if the original recipient
is forwarding their mail to another address and the remote Mail Transport Agents send back
unhelpful bounce messages. The module can also be used to decode bounce recipient addresses.
.SH "FUNCTIONS"
.IX Header "FUNCTIONS"
.IP "\fInew()\fR" 4
.IX Item "new()"
Primarily useful to save typing. So instead of typing \f(CW\*(C`Mail::Verp\*(C'\fR you can say
my\ \f(CW$x\fR\ =\ Mail::Verp\->new; then use \f(CW$x\fR whereever \f(CW\*(C`Mail::Verp\*(C'\fR is usually required.
.Sp
Accepts an optional \f(CW\*(C`separator\*(C'\fR argument for changing the separator, which defaults
to hyphen '\-'.  The value can also be changed using the \f(CW\*(C`separator\*(C'\fR accessor.
.Sp
my\ \f(CW$x\fR\ =\ Mail::Verp\->new(separator\ =>\ '+');
.IP "encode(\s-1LOCAL\-ADDRESS,\s0 REMOTE-ADDRESS)" 4
.IX Item "encode(LOCAL-ADDRESS, REMOTE-ADDRESS)"
Encodes LOCAL-ADDRESS, REMOTE-ADDRESS into a verped address suitable for use
as an envelope return address. It may also be useful to use the same address in
Errors-To and Reply-To headers to compensate for broken Mail Transport Agents.
.Sp
Uses current separator value.
.IP "decode(\s-1VERPED\-ADDRESS\s0)" 4
.IX Item "decode(VERPED-ADDRESS)"
Decodes VERPED-ADDRESS into its constituent parts.
Returns LOCAL-ADDRESS and REMOTE-ADDRESS in list context, REMOTE-ADDRESS in scalar context.
Returns VERPED-ADDRESS if the decoding fails.
.Sp
Uses current separator value.
.IP "separator" 4
.IX Item "separator"
Returns current value of the \s-1VERP \s0\f(CW\*(C`separator\*(C'\fR
.IP "separator(\s-1SEPARATOR\s0)" 4
.IX Item "separator(SEPARATOR)"
Sets new value for \s-1VERP \s0\f(CW\*(C`separator\*(C'\fR and returns the previous value.
.SS "\s-1EXPORT\s0"
.IX Subsection "EXPORT"
None.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\s-1DJ\s0 Bernstein details verps here: http://cr.yp.to/proto/verp.txt.
.PP
Sam Varshavchik proposes an encoding here: http://www.courier\-mta.org/draft\-varshavchik\-verp\-smtpext.txt.
.SH "AUTHOR"
.IX Header "AUTHOR"
Gyepi Sam <gyepi@cpan.org>
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
Copyright 2007 by Gyepi Sam
.PP
This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself.