NAME

Mail::ISO2022JP - compose ISO-2022-JP encoded email

SYNOPSIS

 use Mail::ISO2022JP;
 
 $mail = Mail::ISO2022JP->new;
 
 $mail->add_orig('taro@cpan.tld', 'YAMADA, Taro');
 
 # display-name is omitted:
  $mail->add_dest('kaori@cpan.tld');
 # with a display-name in the US-ASCII characters:
  $mail->add_dest('sakura@cpan.tld', 'Sakura HARUNO');
 # with a display-name containing Japanese characters:
  $mail->add_dest('yuri@cpan.tld', 'NAME CONTAINING JAPANESE CHARS');
 
 # mail subject containing Japanese characters:
  $mail->set('Subject', 'SUBJECT CONTAINING JAPANESE CHARS');
 
 # mail body    containing Japanese characters:
  $mail->set('Body'   , 'BODY CONTAINING JAPANESE CHARS');
 
 # compose
  $mail->compose;
 # output the composed mail
  print $mail->output;

DESCRIPTION

This module is produced mainly for Japanese Perl programmers those who wants to compose an email with Perl extention.

For some reasons, most Japanese internet users have chosen ISO-2022-JP 7bit character encoding for email rather than the other 8bit encodings (eg. EUC-JP, Shift_JIS).

We can use ISO-2022-JP encoded Japanese text as message body safely in an email.

But we should not use ISO-2022-JP encoded Japanese text as a header. We should escape some reserved special characters before composing a header. To enable it, we encode ISO-2022-JP encoded Japanese text with MIME Base64 encoding. Thus MIME Base64 encoded ISO-2022-JP encoded Japanese text is safely using in a mail header.

This module has developed to intend to automate those kinds of operations.

METHODS

new

Creates a new object.

add_orig($addr_spec [, $display_name])

This method specifies a originator address (From: header). The $addr_spec must be valid as an addr-spec in the RFC2822 specification. Be careful, an addr-spec doesn't include the surrounding tokens "<" and ">" (angles).

The $display_name is optional value. It must be valid as an display-name in the RFC2822 specification. It can contain Japanese characters and then it will be encoded with 'B' encoding. When it contains only US-ASCII characters, it will not normaly be encoded. But in the rare case, it might be encoded with 'Q' encoding to shorten line length less than 76 characters (excluding CR LF).

You can use repeatedly this method as much as you wish to specify more than one address. And then you must specify the one Sender: header address.

add_reply()

It is basically same as add_orig() but specifies a Reply-To: originator header address.

sender($addr_spec [, $display_name])

When you specify multiple From: header address, you must specify the Sender: header address. This address must be one address and multiple addresses are not allowed.

add_dest($addr_spec [, $display_name])

This method specifies a destination address (To: header). The $addr_spec must be valid as an addr-spec in the RFC2822 specification. Be careful, an addr-spec doesn't include the surrounding tokens "<" and ">" (angles).

The $display_name is optional value. It must be valid as an display-name in the RFC2822 specification. It can contain Japanese characters and then it will be encoded with 'B' encoding. When it contains only US-ASCII characters, it will not normaly be encoded. But in the rare case, it might be encoded with 'Q' encoding to shorten line length less than 76 characters (excluding CR LF).

You can use repeatedly this method as much as you wish to specify more than one address.

add_dest_cc(), add_dext_bcc()

These are basically same as add_dest() but specifies a Cc: or Bcc: destination header address.

set('Subject', $subject)

Specify the mail subject. $subject can contain Japanese characters. Note that this module runs under Unicode/UTF-8 environment, you should input these data in UTF-8 character encoding.

set('Body', $body)

Specify the mail body. $body can contain Japanese characters. Note that this module runs under Unicode/UTF-8 environment, you should input these data in UTF-8 character encoding.

Note: RFC1468 describes about a line should be tried to keep length within 80 display columns. Then each JIS X 0208 character takes two columns, and the escape sequences do not take any.

set('Date', $date)

Specify the mail origination date. Note that date-time format should be compliant to the format of RFC2822 specification. It is like blow:

 Mon, 10 Mar 2003 18:48:06 +0900

Don't forget to quote the string. If you don't specify date, sendmail program may add automatically on posting.

compose

Compose a formed email.

post *EXPERIMENTAL*

Posts a mail using sendmail program. At the default setting, it is supposed that sendmail program's name is `sendmail' under the systems's PATH environmental variable. You can specify exact location with sendmail() method.

sendmail($path) *EXPERIMENTAL*

Specifies sendmail location. ex. '/usr/bin/sendmail'

SEE ALSO

RFC2822: http://www.ietf.org/rfc/rfc2822.txt (Mail)

RFC2045: http://www.ietf.org/rfc/rfc2045.txt (MIME)

RFC2046: http://www.ietf.org/rfc/rfc2046.txt (MIME)

RFC2047: http://www.ietf.org/rfc/rfc2047.txt (MIME)

RFC1468: http://www.ietf.org/rfc/rfc1468.txt (ISO-2022-JP)

Perl Module: MIME::Base64

Perl Module: Encode

NOTES

This module runs under Unicode/UTF-8 environment (then Perl5.8 or later is required), you should input data in UTF-8 character encoding.

TO DO

To coodinate with the other existing modules about Mail -- to divide and to transfer to any existants of its own functions as much as it could be. (However, it seems not an easy work because of our Japanese charset encoding's double-byte nature and so on...)

THANKS TO:

Koichi TANIGUCHI for the suggestions.

AUTHOR

Masanori HATA <lovewing@geocities.co.jp> (Saitama, JAPAN)

COPYRIGHT

Copyright (c) 2003 Masanori HATA. All rights reserved.

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