/ 
Mail-Make-v0.21.0
River stage zero No dependents
/ Mail::Make::Entity

NAME

Mail::Make::Entity - MIME Part Builder for Mail::Make

SYNOPSIS

use Mail::Make::Entity;

# Build a text/plain part
my $part = Mail::Make::Entity->build(
    type     => 'text/plain',
    charset  => 'utf-8',
    data     => "Hello, World!\n",
) || die( Mail::Make::Entity->error );

# Build a multipart/related container
my $container = Mail::Make::Entity->build(
    type => 'multipart/related',
) || die( Mail::Make::Entity->error );

# Add an inline image with a comma in the filename
my $img = Mail::Make::Entity->build(
    type        => 'image/png',
    path        => '/var/www/images/Yamato,Inc-Logo.png',
    disposition => 'inline',
    cid         => 'logo@yamato-inc',
) || die( Mail::Make::Entity->error );
$container->add_part( $img );

print $container->as_string;

VERSION

v0.4.0

DESCRIPTION

The core MIME part object for Mail::Make. Represents a single MIME entity (either a leaf part with a body, or a multipart container with sub-parts).

The build() class method is the primary factory. It performs strict input validation, automatic RFC 2231 encoding of filenames with special characters, and deterministic Content-Transfer-Encoding selection. It never silently corrupts a message — all invalid inputs produce an explicit error.

CLASS METHOD

build( %params )

Builds and returns a new Mail::Make::Entity. Parameters:

type

MIME type/subtype string. Default: text/plain.

charset

Charset for text/* parts. Validated via Encode. Default: utf-8 for text/* parts if not specified.

encoding

Content-Transfer-Encoding. One of 7bit, 8bit, binary, base64, quoted-printable. Auto-suggested if omitted. binary is rejected for text/* types.

disposition

inline or attachment. Defaults to attachment when a filename is present.

filename

Filename for Content-Type: name= and Content-Disposition: filename=. Values containing commas or other RFC 2045 specials are automatically RFC 2231 encoded. If not provided and path is given, the basename is used.

cid

Content-ID for inline parts (e.g. embedded images). Angle brackets are added automatically if missing.

data

Scalar body content (for in-memory bodies).

path

File path (for on-disk bodies). The file must exist and be readable.

boundary

Boundary string for multipart/* types. Validated against RFC 2046 allowed characters. Auto-generated if omitted.

description

Optional Content-Description value.

Returns undef and sets an error on failure.

METHODS

add_part( $entity )

Appends a Mail::Make::Entity as a sub-part of this entity.

as_string

Returns the serialised entity (headers + blank line + encoded body) as a plain string. This is the form expected by print, string interpolation, and most downstream consumers.

For large messages where avoiding a string copy matters, use "as_string_ref" instead.

as_string_ref

Returns the serialised entity as a scalar reference. No string copy is made: the same buffer used during serialisation is returned directly. Dereference with $$ref when a plain string is needed.

body( [$body] )

Gets or sets the Mail::Make::Body-derived body object.

body_as_string

Returns a scalar reference to the (encoded) body content.

effective_type( [$type] )

Gets or sets the cached MIME type/subtype string.

encode_body

Encodes the body according to the Content-Transfer-Encoding header. No-op if already encoded.

epilogue( [$arrayref] )

Gets or sets the epilogue lines (appended after the closing boundary).

headers( [$headers] )

Gets or sets the Mail::Make::Headers collection.

is_binary

Returns true if the effective MIME type is not a text type.

is_encoded( [$bool] )

Gets or sets the encoded flag.

is_multipart

Returns true if the effective MIME type is multipart/*.

is_text

Returns true if the effective MIME type is a text type.

length

my $bytes = $entity->length;

Returns the exact serialised size in bytes of this entity: headers, the blank CRLF separator, and the encoded body (recursively for multipart entities, including all boundary lines, preamble, and epilogue).

The calculation mirrors "print" exactly without accumulating a serialisation buffer. For singlepart entities the body is encoded first via "encode_body" (if not already done), then "length" in Mail::Make::Body::File (a stat call) or "length" in Mail::Make::Body::InCore (a scalar byte count) is used to obtain the encoded body size — the content is never loaded into a second buffer. Headers are stringified since they are always held in memory.

Returns undef and sets error() on failure.

make_boundary

Generates a unique boundary string.

mime_type

Returns the bare MIME type (without parameters).

parts( [$arrayref | @list] )

Gets or sets the list of sub-part entities.

preamble( [$arrayref] )

Gets or sets the preamble lines (before the first boundary).

print( [$fh] )

Serialises the entity to a filehandle.

Serialises only the body portion to a filehandle.

stringify

Alias for "as_string".

stringify_ref

Alias for "as_string_ref".

stringify_body

Alias for "body_as_string".

stringify_header

Returns the header block as a string.

suggest_encoding

Returns the recommended Content-Transfer-Encoding for this entity's MIME type.

make_multipart( [$subtype] )

$entity->make_multipart( 'mixed' );
$entity->make_multipart( 'alternative' );

Promotes a single-part entity into a multipart/$subtype container in-place. The default subtype is mixed if none is supplied.

If the entity is already multipart, the method returns $self immediately without making any changes.

The existing body (if any) is wrapped into a child entity that preserves the original Content-Type, and that child becomes the first part of the new container. A fresh MIME boundary is generated via "make_boundary".

The outer container's Content-Transfer-Encoding header is removed, as transfer encoding applies to individual parts rather than the container itself.

Returns $self on success, undef on error.

purge

$entity->purge;

Recursively releases all body content held by this entity and its child parts.

For each node in the entity tree, the body object's own purge() method is called (which may, for example, delete a temporary file backing a Mail::Make::Body::File), then the reference is cleared.

Returns $self.

textual_type( $mime_type )

Returns true if the given MIME type is text/* or message/*.

AUTHOR

Jacques Deguest <jack@deguest.jp>

SEE ALSO

RFC 2045, RFC 2046, RFC 2047, RFC 2231

Mail::Make, Mail::Make::Headers, Mail::Make::Body, Mail::Make::Stream::Base64, Mail::Make::Stream::QuotedPrint

COPYRIGHT & LICENSE

Copyright(c) 2026 DEGUEST Pte. Ltd.

All rights reserved.

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