Data.MIME

MIME messages (RFC 2045, RFC 2046 and friends).

Overview

This module extends RFC5322 with types for handling MIME messages. It provides the mime parsing helper function for use with message.

mime :: Headers -> Parser MIME
message mime :: Parser (Message ctx MIME)

The Message data type has a phantom type parameter for context. In this module we use it to track whether the body has content transfer encoding or charset encoding applied. Type aliases are provided for convenince.

data Message ctx a = Message Headers a
data EncStateWire
data EncStateByte

type MIMEMessage = Message EncStateWire MIME
type WireEntity = Message EncStateWire B.ByteString
type ByteEntity = Message EncStateByte B.ByteString
type TextEntity = Message () T.Text

Folds are provided over all leaf entities, and entities that are identified as attachments:

entities :: Fold MIMEMessage WireEntity
attachments :: Fold MIMEMessage WireEntity

Content transfer decoding is performed using the transferDecoded optic. This will convert Quoted-Printable or Base64 encoded entities into their decoded form.

transferDecoded :: Getter WireEntity (Either EncodingError ByteEntity)
transferDecoded :: Getter WireEntity (Either EncodingError ByteEntity)
transferDecoded :: (HasTransferEncoding a, AsTransferEncodingError e) => Getter a (Either e (TransferDecoded a))

Charset decoding is performed using the charsetDecoded optic:

charsetDecoded :: Getter ByteEntity (Either EncodingError TextEntity)
charsetDecoded :: Getter ByteEntity (Either EncodingError TextEntity)
charsetDecoded :: (HasCharset a, AsCharsetError e) => Getter a (Either e (Decoded a))

Examples / HOWTO

Parse a MIME message:

parse (message mime) :: ByteString -> Either String MIMEMessage

Find the first entity with the text/plain content type:

getTextPlain :: MIMEMessage -> Maybe WireEntity
getTextPlain = firstOf (entities . filtered f)
  where
  f = matchContentType "text" (Just "plain") . view (headers . contentType)

Perform content transfer decoding and charset decoding while preserving decode errors:

view transferDecoded >=> view charsetDecoded :: WireEntity -> Either EncodingError TextEntity

Get all attachments (transfer decoded) and their filenames (if specified):

getAttachments :: MIMEMessage -> [(Either EncodingError B.ByteString, Maybe T.Text)]
getAttachments = toListOf (attachments . to (liftA2 (,) content name)
  where
  content = view transferDecodedBytes
  name = preview (headers . contentDisposition . filename)

Create an inline, plain text message and render it:

renderMessage $ createTextPlainMessage "This is a test body"

API

MIME data type

data MIME

MIME message body. Either a single Part, or Multipart. Only the body is represented; preamble and epilogue are not.

Constructors

Part ByteString

Multipart [MIMEMessage]

Instances

Eq MIME

Defined in Data.MIME

Methods

(==) :: MIME -> MIME -> Bool

(/=) :: MIME -> MIME -> Bool

Show MIME

Defined in Data.MIME

Methods

showsPrec :: Int -> MIME -> ShowS

show :: MIME -> String

showList :: [MIME] -> ShowS

mime :: Headers -> Parser MIME

Top-level MIME body parser that uses headers to decide how to parse the body.

Do not use this parser for parsing a nested message. This parser should only be used when the message you want to parse is the whole input. If you use it to parse a nested message it will treat the remainder of the outer message(s) as part of the epilogue.

Preambles and epilogues are discarded.

This parser accepts non-MIME messages, and unconditionally treats them as a single part.

type MIMEMessage = Message EncStateWire MIME

type WireEntity = Message EncStateWire ByteString

type ByteEntity = Message EncStateByte ByteString

type TextEntity = Message () Text

data EncStateWire

Entity is formatted for transfer. Processing requires transfer decoding.

Instances

HasTransferEncoding WireEntity

Defined in Data.MIME

Associated Types

type TransferDecoded WireEntity :: Type

Methods

transferEncodingName :: Getter WireEntity TransferEncodingName

transferEncodedData :: Getter WireEntity ByteString

transferDecoded :: AsTransferEncodingError e => Getter WireEntity (Either e (TransferDecoded WireEntity))

type TransferDecoded WireEntity

Defined in Data.MIME

type TransferDecoded WireEntity = ByteEntity

data EncStateByte

Entity requires content-transfer-encoding to send, and may require charset decoding to read.

Instances

HasCharset ByteEntity

RFC 2046 §4.1.2. defines the default character set to be US-ASCII.

Defined in Data.MIME

Associated Types

type Decoded ByteEntity :: Type

Methods

charsetName :: Getter ByteEntity (Maybe CharsetName)

charsetData :: Getter ByteEntity ByteString

charsetDecoded :: AsCharsetError e => Getter ByteEntity (Either e (Decoded ByteEntity))

charsetEncode :: Decoded ByteEntity -> ByteEntity

type Decoded ByteEntity

Defined in Data.MIME

type Decoded ByteEntity = TextEntity

Accessing and processing entities

entities :: Traversal' MIMEMessage WireEntity

Get all leaf entities from the MIME message

attachments :: Traversal' MIMEMessage WireEntity

Leaf entities with Content-Disposition: attachment

isAttachment :: MIMEMessage -> Bool

MIMEMessage content disposition is an Attachment

transferDecoded :: (HasTransferEncoding a, AsTransferEncodingError e) => Getter a (Either e (TransferDecoded a))

Perform content transfer decoding.

charsetDecoded :: (HasCharset a, AsCharsetError e) => Getter a (Either e (Decoded a))

Structure with the encoded data replaced with Text

Header processing

decodeEncodedWords :: ByteString -> Text

RFC 2047 and RFC 2231 define the encoded-words mechanism for embedding non-ASCII data in headers. This function locates encoded-words and decodes them.

λ> T.putStrLn $ decodeEncodedWords "hello =?utf-8?B?5LiW55WM?=!"
hello 世界!

If parsing fails or the encoding is unrecognised the encoded-word is left unchanged in the result.

λ> T.putStrLn $ decodeEncodedWords "=?utf-8?B?bogus?="
=?utf-8?B?bogus?=

λ> T.putStrLn $ decodeEncodedWords "=?utf-8?X?unrecognised_encoding?="
=?utf-8?X?unrecognised_encoding?=

Language specification is supported (the datum is discarded).

λ> T.putStrLn $ decodeEncodedWords "=?utf-8*es?Q?hola_mundo!?="
hola mundo!

Content-Type header

contentType :: Lens' Headers ContentType

Lens to the content-type header. Probably not a lawful lens.

If the header is not specified or is syntactically invalid, defaultContentType is used. For more info see https://tools.ietf.org/html/rfc2045#section-5.2.

If the Content-Transfer-Encoding is unrecognised, the actual Content-Type value is ignored and application/octet-stream is returned, as required by https://tools.ietf.org/html/rfc2049#section-2.

When setting, if the header already exists it is replaced, otherwise it is added. Unrecognised Content-Transfer-Encoding is ignored when setting.

data ContentType

Content-Type header (RFC 2183). Use parameters to access the parameters. Example:

ContentType "text" "plain" [("charset", "utf-8")]

Constructors

ContentType (CI ByteString) (CI ByteString) Parameters

Instances

Eq ContentType

Equality of Content-Type. Type and subtype are compared case-insensitively and parameters are also compared. Use matchContentType if you just want to match on the media type while ignoring parameters.

Defined in Data.MIME

Methods

(==) :: ContentType -> ContentType -> Bool

(/=) :: ContentType -> ContentType -> Bool

Show ContentType

Defined in Data.MIME

Methods

showsPrec :: Int -> ContentType -> ShowS

show :: ContentType -> String

showList :: [ContentType] -> ShowS

Generic ContentType

Defined in Data.MIME

Associated Types

type Rep ContentType :: Type -> Type

Methods

from :: ContentType -> Rep ContentType x

to :: Rep ContentType x -> ContentType

NFData ContentType

Defined in Data.MIME

Methods

rnf :: ContentType -> ()

HasParameters ContentType

Defined in Data.MIME

Methods

parameters :: Lens' ContentType Parameters

type Rep ContentType

Defined in Data.MIME

type Rep ContentType = D1 (MetaData "ContentType" "Data.MIME" "purebred-email-0.1.0.0-8Bt4ZJ2WL9Q9ZWrzTASNaX" False) (C1 (MetaCons "ContentType" PrefixI False) (S1 (MetaSel (Nothing :: Maybe Symbol) NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 (CI ByteString)) :*: (S1 (MetaSel (Nothing :: Maybe Symbol) NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 (CI ByteString)) :*: S1 (MetaSel (Nothing :: Maybe Symbol) NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 Parameters))))

ctType :: Lens' ContentType (CI ByteString)

ctSubtype :: Lens' ContentType (CI ByteString)

matchContentType

Arguments

:: CI ByteString

type

-> Maybe (CI ByteString)

optional subtype

-> ContentType

-> Bool

Match content type. If Nothing is given for subtype, any subtype is accepted.

ctEq :: ContentType -> ContentType -> Bool

Deprecated: Use matchContentType instead

Are the type and subtype the same? (parameters are ignored)

parseContentType :: Parser ContentType

Parser for Content-Type header

showContentType :: ContentType -> Text

Rendered content type field value for displaying

mimeBoundary :: Traversal' ContentType ByteString

Get the boundary, if specified

Content-Type values

contentTypeTextPlain :: ContentType

text/plain

contentTypeApplicationOctetStream :: ContentType

application/octet-stream

contentTypeMultipartMixed :: ByteString -> ContentType

multipart/mixed; boundary=asdf

defaultContentType :: ContentType

text/plain; charset=us-ascii

Content-Disposition header

contentDisposition :: Traversal' Headers ContentDisposition

Get Content-Disposition header. Unrecognised disposition types are coerced to Attachment in accordance with RFC 2183 §2.8 which states: Unrecognized disposition types should be treated as attachment.

The fold may be empty, e.g. if the header is absent or unparseable.

data ContentDisposition

Content-Disposition header (RFC 2183).

Use parameters to access the parameters.

Constructors

ContentDisposition DispositionType Parameters

Instances

Show ContentDisposition

Defined in Data.MIME

Methods

showsPrec :: Int -> ContentDisposition -> ShowS

show :: ContentDisposition -> String

showList :: [ContentDisposition] -> ShowS

Generic ContentDisposition

Defined in Data.MIME

Associated Types

type Rep ContentDisposition :: Type -> Type

Methods

from :: ContentDisposition -> Rep ContentDisposition x

to :: Rep ContentDisposition x -> ContentDisposition

NFData ContentDisposition

Defined in Data.MIME

Methods

rnf :: ContentDisposition -> ()

HasParameters ContentDisposition

Defined in Data.MIME

Methods

parameters :: Lens' ContentDisposition Parameters

type Rep ContentDisposition

Defined in Data.MIME

type Rep ContentDisposition = D1 (MetaData "ContentDisposition" "Data.MIME" "purebred-email-0.1.0.0-8Bt4ZJ2WL9Q9ZWrzTASNaX" False) (C1 (MetaCons "ContentDisposition" PrefixI False) (S1 (MetaSel (Nothing :: Maybe Symbol) NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 DispositionType) :*: S1 (MetaSel (Nothing :: Maybe Symbol) NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 Parameters)))

data DispositionType

Constructors

Inline

Attachment

Instances

Eq DispositionType

Defined in Data.MIME

Methods

(==) :: DispositionType -> DispositionType -> Bool

(/=) :: DispositionType -> DispositionType -> Bool

Show DispositionType

Defined in Data.MIME

Methods

showsPrec :: Int -> DispositionType -> ShowS

show :: DispositionType -> String

showList :: [DispositionType] -> ShowS

Generic DispositionType

Defined in Data.MIME

Associated Types

type Rep DispositionType :: Type -> Type

Methods

from :: DispositionType -> Rep DispositionType x

to :: Rep DispositionType x -> DispositionType

NFData DispositionType

Defined in Data.MIME

Methods

rnf :: DispositionType -> ()

type Rep DispositionType

Defined in Data.MIME

type Rep DispositionType = D1 (MetaData "DispositionType" "Data.MIME" "purebred-email-0.1.0.0-8Bt4ZJ2WL9Q9ZWrzTASNaX" False) (C1 (MetaCons "Inline" PrefixI False) (U1 :: Type -> Type) :+: C1 (MetaCons "Attachment" PrefixI False) (U1 :: Type -> Type))

dispositionType :: Lens' ContentDisposition DispositionType

filename :: HasParameters a => Traversal' a Text

Traverse the value of the filename parameter (if present).

filenameParameter :: HasParameters a => Lens' a (Maybe EncodedParameterValue)

Access the filename parameter as a Maybe (ParameterValue B.ByteString).

This can be used to read or set the filename parameter (see also the newParameter convenience function):

λ> let hdrs = Headers [("Content-Disposition", "attachment")]
λ> set (contentDisposition . filenameParameter) (Just (newParameter "foo.txt")) hdrs
Headers [("Content-Disposition","attachment; filename=foo.txt")]

Serialisation

renderMessage :: MIMEMessage -> ByteString

Serialise a given MIMEMessage into a ByteString. The message is serialised as is. No additional headers are set.

buildMessage :: MIMEMessage -> Builder

Serialise a given MIMEMessage using a Builder

Mail creation

headerFrom :: Lens' Headers [Mailbox]

headerTo :: Lens' Headers [Address]

headerCC :: Lens' Headers [Address]

headerBCC :: Lens' Headers [Address]

headerDate :: Lens' Headers UTCTime

replyHeaderReferences :: Getter Headers (Maybe ByteString)

Returns a space delimited ByteString with values from identification fields from the parents message Headers. Rules to gather the values are in accordance to RFC5322 - 3.6.4 as follows sorted by priority (first has precedence): * Values from References and `Message-ID` (if any) * Values from 'In-Reply-To' and 'Message-ID' (if any) * Value from 'Message-ID' (in case it's the first reply to a parent mail) * otherwise Nothing is returned indicating that the replying mail should not have a References field.

createAttachmentFromFile :: ContentType -> FilePath -> IO MIMEMessage

Create an attachment from a given file path. Note: The filename content disposition is set to the given FilePath. For privacy reasons, you can unset/change it. See filename for examples.

createAttachment :: ContentType -> Maybe FilePath -> ByteString -> MIMEMessage

Create an attachment from the given file contents. Optionally set the given filename parameter to the given file path.

createTextPlainMessage

Arguments

:: Text

message body

-> MIMEMessage

Create an inline, text/plain, utf-8 encoded message

createMultipartMixedMessage

Arguments

:: ByteString

Boundary

-> [MIMEMessage]

attachments

-> MIMEMessage

Create a mixed MIMEMessage with an inline text/plain part and multiple attachments

Additional headers can be set (e.g. cc) by using At and Ixed, for example:

λ> set (at "subject") (Just "Hey there") $ Headers []
Headers [("subject", "Hey there")]

You can also use the Mailbox instances:

λ> let address = Mailbox (Just "roman") (AddrSpec "roman" (DomainLiteral "192.168.1.1"))
λ> set (at "cc") (Just $ renderMailbox address) $ Headers []
Headers [("cc", "\"roman\" roman@192.168.1.1")]

Re-exports

module Data.RFC5322

module Data.MIME.Parameter

module Data.MIME.Error