{ "mode": "info", "parameter": "Email::MIME", "section": "", "url": "https://www.chedong.com/phpMan.php/info/Email%3A%3AMIME/json", "generated": "2026-07-05T01:32:27Z", "synopsis": "Wait! Before you read this, maybe you just need Email::Stuffer, which\nis a much easier-to-use tool for building simple email messages that\nmight have attachments or both plain text and HTML. If that doesn't do\nit 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 ' ],\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;", "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\nis a much easier-to-use tool for building simple email messages that\nmight have attachments or both plain text and HTML. If that doesn't do\nit 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 ' ],\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\nencoded messages. It takes a message as a string, splits it up into its\nconstituent parts, and allows you access to various parts of the\nmessage. Headers are decoded from MIME encoding.\n", "subsections": [] }, "PERL VERSION": { "content": "This library should run on perls released even a long time ago. It\nshould work on any version of perl released in the last five years.\n\nAlthough it may work on older versions of perl, no guarantee is made\nthat the minimum required version will not be increased. The version\nmay be increased for any reason, and there is no promise that patches\nwill 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\nvery long. Added to that, you 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\nlist of headers pairs to include in the message. The value for each\npair is expected to be a text string that will be MIME-encoded as\nneeded. Alternatively it can be an object with \"asmimestring\" method\nwhich implements conversion of that object to MIME-encoded string.\nThat object method is called with two named input parameters: \"charset\"\nand \"headernamelength\". It should return MIME-encoded representation\nof the object. As of 2017-07-25, the header-value-as-object code is\nvery young, and may yet change.\n\nIn case header name is registered in\n%Email::MIME::Header::headertoclassmap hash then registered class is\nused for conversion from Unicode string to 8bit MIME encoding. Value\ncan be either string or array reference to strings. Object is\nconstructed via method \"fromstring\" with string value (or values in\ncase 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\nof \"headerstr\". Its values will be used verbatim.\n\n\"attributes\" is a hash of MIME attributes to assign to the part, and\nmay override portions of the header set in the \"header\" parameter. The\nhash keys correspond directly to methods for modifying a message from\n\"Email::MIME::Modifier\". The allowed keys are: contenttype, charset,\nname, format, boundary, encoding, disposition, and filename. They will\nbe mapped to \"$attr\\set\" for message modification.\n\nThe \"parts\" parameter is a list reference containing \"Email::MIME\"\nobjects. Elements of the \"parts\" list can also be a non-reference\nstring of data. In that case, an \"Email::MIME\" object will be created\nfor you. Simple checks will determine if the part is binary or not, and\nall parts created in this fashion are encoded with \"base64\", just in\ncase.\n\nIf \"body\" is given instead of \"parts\", it specifies the body to be used\nfor a flat (subpart-less) MIME message. It is assumed to be a sequence\nof octets.\n\nIf \"bodystr\" is given instead of \"body\" or \"parts\", it is assumed to\nbe a character string to be used as the body. If you provide a\n\"bodystr\" parameter, you must provide \"charset\" and \"encoding\"\nattributes.\n\ncontenttypeset\n$email->contenttypeset( 'text/html' );\n\nChange the content type. All \"Content-Type\" header attributes will\nremain 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\n\"undef\", the attribute is removed. All other \"Content-Type\" header\ninformation 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\nis the parameter passed to \"decode\" in Encode and \"encode\" in Encode\nwhen \"bodystr()\", \"bodystrset()\", and \"create()\" are called.\n\nWith the default setting, Email::MIME may crash if the claimed charset\nof a body does not match its contents (for example - utf8 data in a\ntext/plain; charset=us-ascii message).\n\nWith an \"encodecheck\" of 0, the unrecognized bytes will instead be\nreplaced with the \"REPLACEMENT CHARACTER\" (U+0FFFD), and may end up as\neither 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\"\nheader using this method. Your message body, the output of the \"body()\"\nmethod, will remain the same. The raw body, output with the\n\"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\nspecified in the \"Content-Transfer-Encoding\" header, then set the body\nto 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\nis a Unicode string that should be encoded into the message's charset\nbefore being set.\n\nThe charset must already be set, either manually (via the \"attributes\"\nargument to \"create\" or \"charsetset\") or through the \"Content-Type\" of\na parsed message. If the charset can't be determined, an exception is\nthrown.\n\ndispositionset\n$email->dispositionset( 'attachment' );\n\nAlter the \"Content-Disposition\" of a message. All header attributes\nwill remain intact.\n\nfilenameset\n$email->filenameset( 'boo.pdf' );\n\nSets the filename attribute in the \"Content-Disposition\" header. All\nother header information is preserved when setting this attribute.\n\npartsset\n$email->partsset( \\@newparts );\n\nReplaces the parts for an object. Accepts a reference to a list of\n\"Email::MIME\" objects, representing the new parts. If this message was\noriginally a single part, the \"Content-Type\" header will be changed to\n\"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\nof \"partsset\" to make our lives easier. It accepts an array reference\nof 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/]+>//; # simple filter example\n$part->bodyset( $body );\n}\n});\n\nWalks through all the MIME parts in a message and applies a callback to\neach. Accepts a code reference as its only argument. The code reference\nwill be passed a single argument, the current MIME part within the top-\nlevel MIME object. All changes will be applied in place.\n\nheader\nAchtung! Beware this method! In Email::MIME, it means the same as\n\"headerstr\", but on an Email::Simple object, it means \"headerraw\".\nUnless you always know what kind of object you have, you could get one\nof 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)\nstrings as the values to set, rather than pre-encoded byte strings. It\nwill encode them as MIME encoded-words if they contain any control or\n8-bit characters.\n\nAlternatively, values can be objects with \"asmimestring\" method.\nSame as in method \"create\".\n\nheaderstrpairs\nmy @pairs = $email->headerstrpairs;\n\nThis method behaves like \"headerrawpairs\", returning a list of field\nname/value pairs, but the values have been decoded to character\nstrings, 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\ninstances new object via method \"frommimestring\" of specified class.\nInput argument for that class method is list of the raw MIME-encoded\nvalues. If class argument is not specified then class name is taken\nfrom the hash %Email::MIME::Header::headertoclassmap via key field.\nUse class method \"Email::MIME::Header->setclassforheader($class,\n$field)\" for adding new mapping.\n\nparts\nThis returns a list of \"Email::MIME\" objects reflecting the parts of\nthe message. If it's a single-part message, you get the original object\nback.\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\nthe message. If it's a single-part message, this method returns an\nempty 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\ntop-level objects in multi-part messages, this is highly likely to be\nsomething like \"This is a multi-part message in MIME format.\"\n\nbodystr\nThis decodes both the Content-Transfer-Encoding layer of the body (like\nthe \"body\" method) as well as the charset encoding of the body (unlike\nthe \"body\" method), returning a Unicode string.\n\nIf the charset is known, it is used. If there is no charset but the\ncontent type is either \"text/plain\" or \"text/html\", us-ascii is\nassumed. Otherwise, an exception is thrown.\n\nbodyraw\nThis returns the body of the object, but doesn't decode the transfer\nencoding.\n\ndecodehook\nThis method is called before the Email::MIME::Encodings \"decode\"\nmethod, to decode the body of non-binary messages (or binary messages,\nif the \"forcedecodehook\" method returns true). By default, this\nmethod does nothing, but subclasses may define behavior.\n\nThis method could be used to implement the decryption of content in\nsecure 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\nit will return the filename from the headers, but if \"filename\" is\npassed a true parameter, it will generate an appropriate \"stable\"\nfilename 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\nfiles. It will attempt to choose a reasonable extension, falling back\nto dat.\n\ndebugstructure\nmy $description = $email->debugstructure;\n\nThis method returns a string that describes the structure of the MIME\nentity. 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\nwill be processed. It defaults to 10, already higher than legitimate\nmail is ever likely to be. This value may go up over time as the\nparser is improved.\n", "subsections": [] }, "TODO": { "content": "All of the Email::MIME-specific guts should move to a single entry on\nthe object's guts. This will require changes to both Email::MIME and\nEmail::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\n(http://www.bestpractical.com/), Pete Sergeant, and Pobox.com.\n", "subsections": [] }, "AUTHORS": { "content": "o Ricardo SIGNES \n\no Casey West \n\no Simon Cozens \n", "subsections": [] }, "CONTRIBUTORS": { "content": "o Alex Vandiver \n\no Anirvan Chatterjee \n\no Arthur Axel 'fREW' Schmidt \n\no Brian Cassidy \n\no Damian Lukowski \n\no Dan Book \n\no David Steinbrunner \n\no Dotan Dimet \n\no dxdc \n\no Eric Wong \n\no Geraint Edwards \n\no ivulfson <9122139+ivulfson@users.noreply.github.com>\n\no Jesse Luehrs \n\no Kurt Anderson \n\no Lance A. Brown \n\no Matthew Horsfall \n\no memememomo \n\no Michael McClimon \n\no Mishrakk <48946018+Mishrakk@users.noreply.github.com>\n\no Pali \n\no Shawn Sorichetti \n\no Tomohiro Hosaka \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\nthe same terms as the Perl 5 programming language system itself.\n\nperl v5.32.1 2021-12-17 Email::MIME(3pm)", "subsections": [] } }, "summary": "Email::MIME - easy MIME message handling", "flags": [], "examples": [], "see_also": [] }