{
    "mode": "perldoc",
    "parameter": "Mail::Message::Construct::Build",
    "section": "",
    "url": "https://www.chedong.com/phpMan.php/perldoc/Mail%3A%3AMessage%3A%3AConstruct%3A%3ABuild/json",
    "generated": "2026-06-13T06:19:45Z",
    "synopsis": "my $msg1 = Mail::Message->build\n( From => 'me', data => \"only two\\nlines\\n\");\nmy $msg2 = Mail::Message->buildFromBody($body);\nMail::Message->build\n( From     => 'me@myhost.com'\n, To       => 'you@yourhost.com'\n, Subject  => \"Read our folder!\"\n, data     => \\@lines\n, file     => 'folder.pdf'\n)->send(via => 'postfix');",
    "sections": {
        "NAME": {
            "content": "Mail::Message::Construct::Build - building a Mail::Message from components\n",
            "subsections": []
        },
        "SYNOPSIS": {
            "content": "my $msg1 = Mail::Message->build\n( From => 'me', data => \"only two\\nlines\\n\");\n\nmy $msg2 = Mail::Message->buildFromBody($body);\n\nMail::Message->build\n( From     => 'me@myhost.com'\n, To       => 'you@yourhost.com'\n, Subject  => \"Read our folder!\"\n\n, data     => \\@lines\n, file     => 'folder.pdf'\n)->send(via => 'postfix');\n",
            "subsections": []
        },
        "DESCRIPTION": {
            "content": "Complex functionality on Mail::Message objects is implemented in different files which are\nautoloaded. This file implements the building of messages from various simpler components.\n",
            "subsections": []
        },
        "METHODS": {
            "content": "",
            "subsections": [
                {
                    "name": "Constructing a message",
                    "content": "Mail::Message->build( [$message|$part|$body], $content )\nSimplified message object builder. In case a $message or message $part is specified, a new\nmessage is created with the same body to start with, but new headers. A $body may be\nspecified as well. However, there are more ways to add data simply.\n\nThe $content is a list of key-value pairs and header field objects. The keys which start\nwith a capital are used as header-lines. Lower-cased fields are used for other purposes as\nlisted below. Each field may be used more than once. Pairs where the value is \"undef\" are\nignored.\n\nIf more than one \"data\", \"file\", and \"attach\" is specified, a multi-parted message is\ncreated. Some \"Content-*\" fields are treated separately: to enforce the content lines of the\nproduced message body after it has been created. For instance, to explicitly state that you\nwish a \"multipart/alternative\" in stead of the default \"multipart/mixed\". If you wish to\nspecify the type per datum, you need to start playing with Mail::Message::Body objects\nyourself.\n\nThis \"build\" method will use buildFromBody() when the body object has been constructed.\nTogether, they produce your message.\n\n-Option--Default\nattach  undef\ndata    undef\nfile    undef\nfiles   [ ]\nhead    undef\n\nattach => BODY|PART|MESSAGE|ARRAY\nOne attachment to the message. Each attachment can be full $message, a $part, or a $body.\nAny $message will get encapsulated into a \"message/rfc822\" body. You can specify many\nitems (may be of different types) at once.\n\nattach => $folder->message(3)->decoded  # body\nattach => $folder->message(3)           # message\nattach => [ $msg1, $msg2->part(6), $msg3->body ];\n\ndata => STRING|ARRAY-OF-LINES\nThe text for one part, specified as one STRING, or an ARRAY of lines. Each line, including\nthe last, must be terminated by a newline. This argument is passed to\nMail::Message::Body::new(data) to construct one.\n\ndata => [ \"line 1\\n\", \"line 2\\n\" ]     # array of lines\ndata => <<'TEXT'                       # string\nline 1\nline 2\nTEXT\n\nfile => FILENAME|FILEHANDLE|IOHANDLE|ARRAY\nCreate a body where the data is read from the specified FILENAME, FILEHANDLE, or object of\ntype IO::Handle. Also this body is used to create a Mail::Message::Body. [2.119] You may\neven pass more than one file at once: 'file' and 'files' option are equivalent.\n\nmy $in = IO::File->new('/etc/passwd', 'r');\n\nfile  => 'picture.jpg'                   # filename\nfile  => \\*MYINPUTFILE                   # file handle\nfile  => $in                             # any IO::Handle\nfiles => [ 'picture.jpg', \\*MYINPUTFILE, $in ]\n\nopen my $in, '<:raw', '/etc/passwd';    # alternative for IO::File\n\nfiles => ARRAY-OF-FILE\nAlias for option \"file\".\n\nhead => HEAD\nStart with a prepared header, otherwise one is created.\n\nexample:\n\nmy $msg = Mail::Message->build\n( From    => 'me@home.nl'\n, To      => Mail::Address->new('your name', 'you@yourplace.aq')\n, Cc      => 'everyone@example.com'\n, Subject => \"Let's talk\",\n, $othermessage->get('Bcc')\n\n, data   => [ \"This is\\n\", \"the first part of\\n\", \"the message\\n\" ]\n, file   => 'myself.gif'\n, file   => 'you.jpg'\n, attach => $signature\n);\n\nmy $msg = Mail::Message->build\n( To     => 'you'\n, 'Content-Type' => 'text/html'\n, data   => \"<html></html>\"\n);\n\nMail::Message->buildFromBody($body, [$head], $headers)\nShape a message around a $body. Bodies have information about their content in them, which\nis used to construct a header for the message. You may specify a $head object which is\npre-initialized, or one is created for you (also when $head is \"undef\"). Next to that, more\n$headers can be specified which are stored in that header.\n\nHeader fields are added in order, and before the header lines as defined by the body are\ntaken. They may be supplied as key-value pairs or Mail::Message::Field objects. In case of a\nkey-value pair, the field's name is to be used as key and the value is a string, address\n(Mail::Address object), or array of addresses.\n\nA \"Date\", \"Message-Id\", and \"MIME-Version\" field are added unless supplied.\n\nexample:\n\nmy $type = Mail::Message::Field->new('Content-Type', 'text/html'\n, 'charset=\"us-ascii\"');\n\nmy @to   = ( Mail::Address->new('Your name', 'you@example.com')\n, 'world@example.info'\n);\n\nmy $msg  = Mail::Message->buildFromBody\n( $body\n, From => 'me@example.nl'\n, To   => \\@to\n, $type\n);\n"
                }
            ]
        },
        "DETAILS": {
            "content": "",
            "subsections": [
                {
                    "name": "Building a message",
                    "content": "Rapid building\nMost messages you need to construct are relatively simple. Therefore, this module provides a\nmethod to prepare a message with only one method call: build().\n\nCompared to MIME::Entity::build()\nThe \"build\" method in MailBox is modelled after the \"build\" method as provided by MIMETools, but\nwith a few simplifications:\n\nWhen a keys starts with a capital, than it is always a header field\nWhen a keys is lower-cased, it is always something else\nYou use the real field-names, not abbreviations\nAll field names are accepted\nYou may specify field objects between key-value pairs\nA lot of facts are auto-detected, like content-type and encoding\nYou can create a multipart at once\n\nHum, reading the list above... what is equivalent? MIME::Entity is not that simple after all!\nLet's look at an example from MIME::Entity's manual page:\n\n### Create the top-level, and set up the mail headers:\n$top = MIME::Entity->build(Type     => \"multipart/mixed\",\nFrom     => 'me@myhost.com',\nTo       => 'you@yourhost.com',\nSubject  => \"Hello, nurse!\");\n\n### Attachment #1: a simple text document:\n$top->attach(Path=>\"./testin/short.txt\");\n\n### Attachment #2: a GIF file:\n$top->attach(Path        => \"./docs/mime-sm.gif\",\nType        => \"image/gif\",\nEncoding    => \"base64\");\n\n### Attachment #3: text we'll create with text we have on-hand:\n$top->attach(Data => $contents);\n\nThe MailBox equivalent could be\n\nmy $msg = Mail::Message->build\n( From     => 'me@myhost.com'\n, To       => 'you@yourhost.com'\n, Subject  => \"Hello, nurse!\"\n\n, file     => \"./testin/short.txt\"\n, file     => \"./docs/mime-sm.gif\"\n, data     => $contents\n);\n\nOne of the simplifications is that MIME::Types is used to lookup the right content type and\noptimal transfer encoding. Good values for content-disposition and such are added as well.\n\nbuild, starting with nothing\nSee build().\n\nbuildFromBody, body becomes message\nSee buildFromBody().\n\nThe Content-* fields\nThe various \"Content-*\" fields are not as harmless as they look. For instance, the\n\"Content-Type\" field will have an effect on the default transfer encoding.\n\nWhen a message is built this way:\n\nmy $msg = Mail::Message->build\n( 'Content-Type' => 'video/mpeg3'\n, 'Content-Transfer-Encoding' => 'base64'\n, 'Content-Disposition' => 'attachment'\n, file => '/etc/passwd'\n);\n\nthen first a \"text/plain\" body is constructed (MIME::Types does not find an extension on the\nfilename so defaults to \"text/plain\"), with no encoding. Only when that body is ready, the new\ntype and requested encodings are set. The content of the body will get base64 encoded, because\nit is requested that way.\n\nWhat basically happens is this:\n\nmy $head = ...other header lines...;\nmy $body = Mail::Message::Body::Lines->new(file => '/etc/passwd');\n$body->type('video/mpeg3');\n$body->transferEncoding('base64');\n$body->diposition('attachment');\nmy $msg  = Mail::Message->buildFromBody($body, $head);\n\nA safer way to construct the message is:\n\nmy $body = Mail::Message::Body::Lines->new\n( file              => '/etc/passwd'\n, mimetype         => 'video/mpeg3'\n, transferencoding => 'base64'\n, disposition       => 'attachment'\n);\n\nmy $msg  = Mail::Message->buildFromBody\n( $body\n, ...other header lines...\n);\n\nIn the latter program, you will immediately start with a body of the right type.\n"
                }
            ]
        },
        "DIAGNOSTICS": {
            "content": "Error: Only build() Mail::Message's; they are not in a folder yet\nYou may wish to construct a message to be stored in a some kind of folder, but you need to\ndo that in two steps. First, create a normal Mail::Message, and then add it to the folder.\nDuring this Mail::Box::addMessage() process, the message will get coerce()-d into the right\nmessage type, adding storage information and the like.\n",
            "subsections": []
        },
        "SEE ALSO": {
            "content": "This module is part of Mail-Message distribution version 3.012, built on February 11, 2022.\nWebsite: http://perl.overmeer.net/CPAN/\n",
            "subsections": []
        },
        "LICENSE": {
            "content": "Copyrights 2001-2022 by [Mark Overmeer <markov@cpan.org>]. For other contributors see ChangeLog.\n\nThis program is free software; you can redistribute it and/or modify it under the same terms as\nPerl itself. See http://dev.perl.org/licenses/\n",
            "subsections": []
        }
    },
    "summary": "Mail::Message::Construct::Build - building a Mail::Message from components",
    "flags": [],
    "examples": [],
    "see_also": []
}