NAME

Lingua::JA::Mail::Header - build ISO-2022-JP charset 'B' encoding mail header fields

SYNOPSIS

use Lingua::JA::Mail::Header;

$header = Lingua::JA::Mail::Header->new;

$header->add_from('taro@cpan.tld', 'YAMADA, Taro');

# display-name is omitted:
 $header->add_to('kaori@cpan.tld');
# with a display-name in the US-ASCII characters:
 $header->add_to('sakura@cpan.tld', 'Sakura HARUNO');
# with a display-name contains Japanese characters:
 $header->add_to('yuri@cpan.tld', 'NAME CONTAINING JAPANESE CHARS');

# mail subject contains Japanese characters:
 $header->subject('SUBJECT CONTAINING JAPANESE CHARS');

# build and output the header fields
 print $header->build;

DESCRIPTION

This module enables you to build mail header fields from a string which may contain some Japanese characters.

If a string can contain Japanese characters, it will be encoded with 'ISO-2022-JP' charset 'B' encoding.

METHODS

new

Create a new object.

add_from($addr_spec [, $display_name])

This method specifies a originator address (the From: header field). 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.

Although RFC2822 describes that the origination date field and the originator address field(s) are the only required header fields, this module would not care to omit those header fields. Since MTA may modify such omittions and you would intended to do.

sender($addr_spec [, $display_name])

This method specifies the sender address (the Sender: header field). You can specify only one address of this header.

add_reply($addr_spec [, $display_name])

It is basically same as add_from() but specifies the Reply-To: header field.

add_to($addr_spec [, $display_name])

This method specifies a destination address (the To: header field). 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_cc($addr_spec [, $display_name])

It is basically same as add_to() but specifies the Cc: header field.

add_bcc($addr_spec [, $display_name])

It is basically same as add_to() but specifies the Bcc: header field.

subject($unstructured)

This method specifies the mail subject (Suject: header field). The $unstructured is valid as an unstructured in the RFC2822 specification. It can contain Japanese characters.

date($date_time)

This method specifies the origination date-time of the mail (Date: header field). The format of date-time should be compliant to the RFC2822 specification. For example:

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

Although RFC2822 describes that the origination date field and the originator address field(s) are the only required header fields, this module would not care to omit those header fields. Since MTA may modify such omittions and you would intended to do.

build

Build and return the header fields.

set($entity, $value)

You can add a free-style header directly with this method. For example, if you want to specify the X-Mailer: header field with value of 'Perl 5.8.0':

$header->set('X-Mailer', 'Perl 5.8.0');

However, when you use this method, you must be in conformity with the RFC2822 specification by yourself.

SEE ALSO

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

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 (hence Perl5.8 or later is required), you should input data in UTF-8 character encoding.

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.