{
    "content": [
        {
            "type": "text",
            "text": "# Email::MIME (perldoc)\n\n## NAME\n\nEmail::MIME - easy MIME message handling\n\n## SYNOPSIS\n\nWait! Before you read this, maybe you just need Email::Stuffer, which is a much easier-to-use\ntool for building simple email messages that might have attachments or both plain text and HTML.\nIf that doesn't do it for you, then by all means keep reading.\nuse Email::MIME;\nmy $parsed = Email::MIME->new($message);\nmy @parts = $parsed->parts; # These will be Email::MIME objects, too.\nmy $decoded = $parsed->body;\nmy $nondecoded = $parsed->bodyraw;\nmy $contenttype = $parsed->contenttype;\n...or...\nuse Email::MIME;\nuse IO::All;\n# multipart message\nmy @parts = (\nEmail::MIME->create(\nattributes => {\nfilename     => \"report.pdf\",\ncontenttype => \"application/pdf\",\nencoding     => \"quoted-printable\",\nname         => \"2004-financials.pdf\",\n},\nbody => io( \"2004-financials.pdf\" )->binary->all,\n),\nEmail::MIME->create(\nattributes => {\ncontenttype => \"text/plain\",\ndisposition  => \"attachment\",\ncharset      => \"US-ASCII\",\n},\nbodystr => \"Hello there!\",\n),\n);\nmy $email = Email::MIME->create(\nheaderstr => [\nFrom => 'casey@geeknest.com',\nTo => [ 'user1@host.com', 'Name <user2@host.com>' ],\nCc => Email::Address::XS->new(\"Display Name \\N{U+1F600}\", 'user@example.com'),\n],\nparts      => [ @parts ],\n);\n# nesting parts\n$email->partsset(\n[\n$email->parts,\nEmail::MIME->create( parts => [ @parts ] ),\n],\n);\n# standard modifications\n$email->headerstrset( 'X-PoweredBy' => 'RT v3.0'      );\n$email->headerstrset( To            => rcpts()        );\n$email->headerstrset( Cc            => auxrcpts()    );\n$email->headerstrset( Bcc           => sekritrcpts() );\n# more advanced\n$->encodingset( 'base64' ) for $email->parts;\n# Quick multipart creation\nmy $email = Email::MIME->create(\nheaderstr => [\nFrom => 'my@address',\nTo   => 'your@address',\n],\nparts => [\nq[This is part one],\nq[This is part two],\nq[These could be binary too],\n],\n);\nprint $email->asstring;\n\n## DESCRIPTION\n\nThis is an extension of the Email::Simple module, to handle MIME encoded messages. It takes a\nmessage as a string, splits it up into its constituent parts, and allows you access to various\nparts of the message. Headers are decoded from MIME encoding.\n\n## Sections\n\n- **NAME**\n- **VERSION**\n- **SYNOPSIS**\n- **DESCRIPTION**\n- **PERL VERSION**\n- **METHODS**\n- **CONFIGURATION**\n- **TODO**\n- **SEE ALSO**\n- **THANKS**\n- **AUTHORS**\n- **CONTRIBUTORS**\n- **COPYRIGHT AND LICENSE**\n\nUse structuredContent.sections for detailed options, examples, and full documentation.\n"
        }
    ],
    "structuredContent": {
        "command": "Email::MIME",
        "section": "",
        "mode": "perldoc",
        "summary": "Email::MIME - easy MIME message handling",
        "synopsis": "Wait! Before you read this, maybe you just need Email::Stuffer, which is a much easier-to-use\ntool for building simple email messages that might have attachments or both plain text and HTML.\nIf that doesn't do it for you, then by all means keep reading.\nuse Email::MIME;\nmy $parsed = Email::MIME->new($message);\nmy @parts = $parsed->parts; # These will be Email::MIME objects, too.\nmy $decoded = $parsed->body;\nmy $nondecoded = $parsed->bodyraw;\nmy $contenttype = $parsed->contenttype;\n...or...\nuse Email::MIME;\nuse IO::All;\n# multipart message\nmy @parts = (\nEmail::MIME->create(\nattributes => {\nfilename     => \"report.pdf\",\ncontenttype => \"application/pdf\",\nencoding     => \"quoted-printable\",\nname         => \"2004-financials.pdf\",\n},\nbody => io( \"2004-financials.pdf\" )->binary->all,\n),\nEmail::MIME->create(\nattributes => {\ncontenttype => \"text/plain\",\ndisposition  => \"attachment\",\ncharset      => \"US-ASCII\",\n},\nbodystr => \"Hello there!\",\n),\n);\nmy $email = Email::MIME->create(\nheaderstr => [\nFrom => 'casey@geeknest.com',\nTo => [ 'user1@host.com', 'Name <user2@host.com>' ],\nCc => Email::Address::XS->new(\"Display Name \\N{U+1F600}\", 'user@example.com'),\n],\nparts      => [ @parts ],\n);\n# nesting parts\n$email->partsset(\n[\n$email->parts,\nEmail::MIME->create( parts => [ @parts ] ),\n],\n);\n# standard modifications\n$email->headerstrset( 'X-PoweredBy' => 'RT v3.0'      );\n$email->headerstrset( To            => rcpts()        );\n$email->headerstrset( Cc            => auxrcpts()    );\n$email->headerstrset( Bcc           => sekritrcpts() );\n# more advanced\n$->encodingset( 'base64' ) for $email->parts;\n# Quick multipart creation\nmy $email = Email::MIME->create(\nheaderstr => [\nFrom => 'my@address',\nTo   => 'your@address',\n],\nparts => [\nq[This is part one],\nq[This is part two],\nq[These could be binary too],\n],\n);\nprint $email->asstring;",
        "tldr_summary": null,
        "tldr_examples": [],
        "tldr_source": null,
        "flags": [],
        "examples": [],
        "see_also": [],
        "section_outline": [
            {
                "name": "NAME",
                "lines": 2,
                "subsections": []
            },
            {
                "name": "VERSION",
                "lines": 2,
                "subsections": []
            },
            {
                "name": "SYNOPSIS",
                "lines": 80,
                "subsections": []
            },
            {
                "name": "DESCRIPTION",
                "lines": 4,
                "subsections": []
            },
            {
                "name": "PERL VERSION",
                "lines": 7,
                "subsections": []
            },
            {
                "name": "METHODS",
                "lines": 248,
                "subsections": []
            },
            {
                "name": "CONFIGURATION",
                "lines": 4,
                "subsections": []
            },
            {
                "name": "TODO",
                "lines": 3,
                "subsections": []
            },
            {
                "name": "SEE ALSO",
                "lines": 2,
                "subsections": []
            },
            {
                "name": "THANKS",
                "lines": 3,
                "subsections": []
            },
            {
                "name": "AUTHORS",
                "lines": 6,
                "subsections": []
            },
            {
                "name": "CONTRIBUTORS",
                "lines": 44,
                "subsections": []
            },
            {
                "name": "COPYRIGHT AND LICENSE",
                "lines": 5,
                "subsections": []
            }
        ],
        "sections": {
            "NAME": {
                "content": "Email::MIME - easy MIME message handling\n",
                "subsections": []
            },
            "VERSION": {
                "content": "version 1.952\n",
                "subsections": []
            },
            "SYNOPSIS": {
                "content": "Wait! Before you read this, maybe you just need Email::Stuffer, which is a much easier-to-use\ntool for building simple email messages that might have attachments or both plain text and HTML.\nIf that doesn't do it for you, then by all means keep reading.\n\nuse Email::MIME;\nmy $parsed = Email::MIME->new($message);\n\nmy @parts = $parsed->parts; # These will be Email::MIME objects, too.\nmy $decoded = $parsed->body;\nmy $nondecoded = $parsed->bodyraw;\n\nmy $contenttype = $parsed->contenttype;\n\n...or...\n\nuse Email::MIME;\nuse IO::All;\n\n# multipart message\nmy @parts = (\nEmail::MIME->create(\nattributes => {\nfilename     => \"report.pdf\",\ncontenttype => \"application/pdf\",\nencoding     => \"quoted-printable\",\nname         => \"2004-financials.pdf\",\n},\nbody => io( \"2004-financials.pdf\" )->binary->all,\n),\nEmail::MIME->create(\nattributes => {\ncontenttype => \"text/plain\",\ndisposition  => \"attachment\",\ncharset      => \"US-ASCII\",\n},\nbodystr => \"Hello there!\",\n),\n);\n\nmy $email = Email::MIME->create(\nheaderstr => [\nFrom => 'casey@geeknest.com',\nTo => [ 'user1@host.com', 'Name <user2@host.com>' ],\nCc => Email::Address::XS->new(\"Display Name \\N{U+1F600}\", 'user@example.com'),\n],\nparts      => [ @parts ],\n);\n\n# nesting parts\n$email->partsset(\n[\n$email->parts,\nEmail::MIME->create( parts => [ @parts ] ),\n],\n);\n\n# standard modifications\n$email->headerstrset( 'X-PoweredBy' => 'RT v3.0'      );\n$email->headerstrset( To            => rcpts()        );\n$email->headerstrset( Cc            => auxrcpts()    );\n$email->headerstrset( Bcc           => sekritrcpts() );\n\n# more advanced\n$->encodingset( 'base64' ) for $email->parts;\n\n# Quick multipart creation\nmy $email = Email::MIME->create(\nheaderstr => [\nFrom => 'my@address',\nTo   => 'your@address',\n],\nparts => [\nq[This is part one],\nq[This is part two],\nq[These could be binary too],\n],\n);\n\nprint $email->asstring;\n",
                "subsections": []
            },
            "DESCRIPTION": {
                "content": "This is an extension of the Email::Simple module, to handle MIME encoded messages. It takes a\nmessage as a string, splits it up into its constituent parts, and allows you access to various\nparts of the message. Headers are decoded from MIME encoding.\n",
                "subsections": []
            },
            "PERL VERSION": {
                "content": "This library should run on perls released even a long time ago. It should work on any version of\nperl released in the last five years.\n\nAlthough it may work on older versions of perl, no guarantee is made that the minimum required\nversion will not be increased. The version may be increased for any reason, and there is no\npromise that patches will be accepted to lower the minimum required perl.\n",
                "subsections": []
            },
            "METHODS": {
                "content": "Please see Email::Simple for the base set of methods. It won't take very long. Added to that,\nyou have:\n\ncreate\nmy $single = Email::MIME->create(\nheaderstr => [ ... ],\nbodystr   => '...',\nattributes => { ... },\n);\n\nmy $multi = Email::MIME->create(\nheaderstr => [ ... ],\nparts      => [ ... ],\nattributes => { ... },\n);\n\nThis method creates a new MIME part. The \"headerstr\" parameter is a list of headers pairs to\ninclude in the message. The value for each pair is expected to be a text string that will be\nMIME-encoded as needed. Alternatively it can be an object with \"asmimestring\" method which\nimplements conversion of that object to MIME-encoded string. That object method is called with\ntwo named input parameters: \"charset\" and \"headernamelength\". It should return MIME-encoded\nrepresentation of the object. As of 2017-07-25, the header-value-as-object code is very young,\nand may yet change.\n\nIn case header name is registered in %Email::MIME::Header::headertoclassmap hash then\nregistered class is used for conversion from Unicode string to 8bit MIME encoding. Value can be\neither string or array reference to strings. Object is constructed via method \"fromstring\" with\nstring value (or values in case of array reference) and converted to MIME-encoded string via\n\"asmimestring\" method.\n\nA similar \"header\" parameter can be provided in addition to or instead of \"headerstr\". Its\nvalues will be used verbatim.\n\n\"attributes\" is a hash of MIME attributes to assign to the part, and may override portions of\nthe header set in the \"header\" parameter. The hash keys correspond directly to methods for\nmodifying a message from \"Email::MIME::Modifier\". The allowed keys are: contenttype, charset,\nname, format, boundary, encoding, disposition, and filename. They will be mapped to \"$attr\\set\"\nfor message modification.\n\nThe \"parts\" parameter is a list reference containing \"Email::MIME\" objects. Elements of the\n\"parts\" list can also be a non-reference string of data. In that case, an \"Email::MIME\" object\nwill be created for you. Simple checks will determine if the part is binary or not, and all\nparts created in this fashion are encoded with \"base64\", just in case.\n\nIf \"body\" is given instead of \"parts\", it specifies the body to be used for a flat\n(subpart-less) MIME message. It is assumed to be a sequence of octets.\n\nIf \"bodystr\" is given instead of \"body\" or \"parts\", it is assumed to be a character string to\nbe used as the body. If you provide a \"bodystr\" parameter, you must provide \"charset\" and\n\"encoding\" attributes.\n\ncontenttypeset\n$email->contenttypeset( 'text/html' );\n\nChange the content type. All \"Content-Type\" header attributes will remain intact.\n\ncharsetset\nnameset\nformatset\nboundaryset\n$email->charsetset( 'UTF-8' );\n$email->nameset( 'somefilename.txt' );\n$email->formatset( 'flowed' );\n$email->boundaryset( undef ); # remove the boundary\n\nThese four methods modify common \"Content-Type\" attributes. If set to \"undef\", the attribute is\nremoved. All other \"Content-Type\" header information is preserved when modifying an attribute.\n\nencodecheck\nencodecheckset\n$email->encodecheck;\n$email->encodecheckset(0);\n$email->encodecheckset(Encode::FBDEFAULT);\n\nGets/sets the current \"encodecheck\" setting (default: *FBCROAK*). This is the parameter passed\nto \"decode\" in Encode and \"encode\" in Encode when \"bodystr()\", \"bodystrset()\", and \"create()\"\nare called.\n\nWith the default setting, Email::MIME may crash if the claimed charset of a body does not match\nits contents (for example - utf8 data in a text/plain; charset=us-ascii message).\n\nWith an \"encodecheck\" of 0, the unrecognized bytes will instead be replaced with the\n\"REPLACEMENT CHARACTER\" (U+0FFFD), and may end up as either that or question marks (?).\n\nSee \"Handling Malformed Data\" in Encode for more information.\n\nencodingset\n$email->encodingset( 'base64' );\n$email->encodingset( 'quoted-printable' );\n$email->encodingset( '8bit' );\n\nConvert the message body and alter the \"Content-Transfer-Encoding\" header using this method.\nYour message body, the output of the \"body()\" method, will remain the same. The raw body, output\nwith the \"bodyraw()\" method, will be changed to reflect the new encoding.\n\nbodyset\n$email->bodyset( $unencodedbodystring );\n\nThis method will encode the new body you send using the encoding specified in the\n\"Content-Transfer-Encoding\" header, then set the body to the new encoded body.\n\nThis method overrides the default \"bodyset()\" method.\n\nbodystrset\n$email->bodystrset($unicodestr);\n\nThis method behaves like \"bodyset\", but assumes that the given value is a Unicode string that\nshould be encoded into the message's charset before being set.\n\nThe charset must already be set, either manually (via the \"attributes\" argument to \"create\" or\n\"charsetset\") or through the \"Content-Type\" of a parsed message. If the charset can't be\ndetermined, an exception is thrown.\n\ndispositionset\n$email->dispositionset( 'attachment' );\n\nAlter the \"Content-Disposition\" of a message. All header attributes will remain intact.\n\nfilenameset\n$email->filenameset( 'boo.pdf' );\n\nSets the filename attribute in the \"Content-Disposition\" header. All other header information is\npreserved when setting this attribute.\n\npartsset\n$email->partsset( \\@newparts );\n\nReplaces the parts for an object. Accepts a reference to a list of \"Email::MIME\" objects,\nrepresenting the new parts. If this message was originally a single part, the \"Content-Type\"\nheader will be changed to \"multipart/mixed\", and given a new boundary attribute.\n\npartsadd\n$email->partsadd( \\@moreparts );\n\nAdds MIME parts onto the current MIME part. This is a simple extension of \"partsset\" to make\nour lives easier. It accepts an array reference of additional parts.\n\nwalkparts\n$email->walkparts(sub {\nmy ($part) = @;\nreturn if $part->subparts; # multipart\n\nif ( $part->contenttype =~ m[text/html]i ) {\nmy $body = $part->body;\n$body =~ s/<link [^>]+>//; # simple filter example\n$part->bodyset( $body );\n}\n});\n\nWalks through all the MIME parts in a message and applies a callback to each. Accepts a code\nreference as its only argument. The code reference will be passed a single argument, the current\nMIME part within the top-level MIME object. All changes will be applied in place.\n\nheader\nAchtung! Beware this method! In Email::MIME, it means the same as \"headerstr\", but on an\nEmail::Simple object, it means \"headerraw\". Unless you always know what kind of object you\nhave, you could get one of two significantly different behaviors.\n\nTry to use either \"headerstr\" or \"headerraw\" as appropriate.\n\nheaderstrset\n$email->headerstrset($headername => @valuestrings);\n\nThis behaves like \"headerrawset\", but expects Unicode (character) strings as the values to\nset, rather than pre-encoded byte strings. It will encode them as MIME encoded-words if they\ncontain any control or 8-bit characters.\n\nAlternatively, values can be objects with \"asmimestring\" method. Same as in method \"create\".\n\nheaderstrpairs\nmy @pairs = $email->headerstrpairs;\n\nThis method behaves like \"headerrawpairs\", returning a list of field name/value pairs, but the\nvalues have been decoded to character strings, when possible.\n\nheaderasobj\nmy $firstobj = $email->headerasobj($field);\nmy $nthobj   = $email->headerasobj($field, $index);\nmy @allobjs  = $email->headerasobj($field);\n\nmy $nthobjofclass  = $email->headerasobj($field, $index, $class);\nmy @allobjsofclass = $email->headerasobj($field, undef, $class);\n\nThis method returns an object representation of the header value. It instances new object via\nmethod \"frommimestring\" of specified class. Input argument for that class method is list of\nthe raw MIME-encoded values. If class argument is not specified then class name is taken from\nthe hash %Email::MIME::Header::headertoclassmap via key field. Use class method\n\"Email::MIME::Header->setclassforheader($class, $field)\" for adding new mapping.\n\nparts\nThis returns a list of \"Email::MIME\" objects reflecting the parts of the message. If it's a\nsingle-part message, you get the original object back.\n\nIn scalar context, this method returns the number of parts.\n\nThis is a stupid method. Don't use it.\n\nsubparts\nThis returns a list of \"Email::MIME\" objects reflecting the parts of the message. If it's a\nsingle-part message, this method returns an empty list.\n\nIn scalar context, this method returns the number of subparts.\n\nbody\nThis decodes and returns the body of the object *as a byte string*. For top-level objects in\nmulti-part messages, this is highly likely to be something like \"This is a multi-part message in\nMIME format.\"\n\nbodystr\nThis decodes both the Content-Transfer-Encoding layer of the body (like the \"body\" method) as\nwell as the charset encoding of the body (unlike the \"body\" method), returning a Unicode string.\n\nIf the charset is known, it is used. If there is no charset but the content type is either\n\"text/plain\" or \"text/html\", us-ascii is assumed. Otherwise, an exception is thrown.\n\nbodyraw\nThis returns the body of the object, but doesn't decode the transfer encoding.\n\ndecodehook\nThis method is called before the Email::MIME::Encodings \"decode\" method, to decode the body of\nnon-binary messages (or binary messages, if the \"forcedecodehook\" method returns true). By\ndefault, this method does nothing, but subclasses may define behavior.\n\nThis method could be used to implement the decryption of content in secure email, for example.\n\ncontenttype\nThis is a shortcut for access to the content type header.\n\nfilename\nThis provides the suggested filename for the attachment part. Normally it will return the\nfilename from the headers, but if \"filename\" is passed a true parameter, it will generate an\nappropriate \"stable\" filename if one is not found in the MIME headers.\n\ninventfilename\nmy $filename = Email::MIME->inventfilename($contenttype);\n\nThis routine is used by \"filename\" to generate filenames for attached files. It will attempt to\nchoose a reasonable extension, falling back to dat.\n\ndebugstructure\nmy $description = $email->debugstructure;\n\nThis method returns a string that describes the structure of the MIME entity. For example:\n\n+ multipart/alternative; boundary=\"=NextPart2\"; charset=\"BIG-5\"\n+ text/plain\n+ text/html\n",
                "subsections": []
            },
            "CONFIGURATION": {
                "content": "The variable $Email::MIME::MAXDEPTH is the maximum depth of parts that will be processed. It\ndefaults to 10, already higher than legitimate mail is ever likely to be. This value may go up\nover time as the parser is improved.\n",
                "subsections": []
            },
            "TODO": {
                "content": "All of the Email::MIME-specific guts should move to a single entry on the object's guts. This\nwill require changes to both Email::MIME and Email::MIME::Modifier, sadly.\n",
                "subsections": []
            },
            "SEE ALSO": {
                "content": "Email::Simple, Email::MIME::Modifier, Email::MIME::Creator.\n",
                "subsections": []
            },
            "THANKS": {
                "content": "This module was generously sponsored by Best Practical (http://www.bestpractical.com/), Pete\nSergeant, and Pobox.com.\n",
                "subsections": []
            },
            "AUTHORS": {
                "content": "*   Ricardo SIGNES <rjbs@semiotic.systems>\n\n*   Casey West <casey@geeknest.com>\n\n*   Simon Cozens <simon@cpan.org>\n",
                "subsections": []
            },
            "CONTRIBUTORS": {
                "content": "*   Alex Vandiver <alexmv@mit.edu>\n\n*   Anirvan Chatterjee <anirvan@users.noreply.github.com>\n\n*   Arthur Axel 'fREW' Schmidt <frioux@gmail.com>\n\n*   Brian Cassidy <bricas@cpan.org>\n\n*   Damian Lukowski <damian.lukowski@credativ.de>\n\n*   Dan Book <grinnz@gmail.com>\n\n*   David Steinbrunner <dsteinbrunner@pobox.com>\n\n*   Dotan Dimet <dotan@corky.net>\n\n*   dxdc <dan@element26.net>\n\n*   Eric Wong <e@80x24.org>\n\n*   Geraint Edwards <gedge-oss@yadn.org>\n\n*   ivulfson <9122139+ivulfson@users.noreply.github.com>\n\n*   Jesse Luehrs <doy@tozt.net>\n\n*   Kurt Anderson <kboth@drkurt.com>\n\n*   Lance A. Brown <lance@bearcircle.net>\n\n*   Matthew Horsfall <wolfsage@gmail.com>\n\n*   memememomo <memememomo@gmail.com>\n\n*   Michael McClimon <michael@mcclimon.org>\n\n*   Mishrakk <48946018+Mishrakk@users.noreply.github.com>\n\n*   Pali <pali@cpan.org>\n\n*   Shawn Sorichetti <ssoriche@coloredblocks.com>\n\n*   Tomohiro Hosaka <bokutin@bokut.in>\n",
                "subsections": []
            },
            "COPYRIGHT AND LICENSE": {
                "content": "This software is copyright (c) 2004 by Simon Cozens and Casey West.\n\nThis is free software; you can redistribute it and/or modify it under the same terms as the Perl\n5 programming language system itself.\n",
                "subsections": []
            }
        }
    }
}