NAME

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

SYNOPSIS

 use Mail::ISO2022JP;
 
 $mail = Mail::ISO2022JP->new;
 
 $mail->set('From_addr', 'taro@cpan.tld');
 
 # 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 mainly for Japanese Perl programmers those who wants to compose an email.

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.

set('From_addr', $address)

Specify the originator address. $address should be valid as email address.

add_dest($addr_spec [, $display_name])

This method specifies a destination address. 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.

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: For the purpose to free from the rule that enforce user to line fold, though ISO-2022-JP is a 7bit encoding, body text is encoded again with Base64 internally.

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)

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

enable originator name contains Japanese characters.

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.