Represents a `DecodeError` with the message and the cause.


Error

DecodeError

Represents an `EncodeError` with the message and the cause.


EncodeError

Defines the common error type for the module.


Represents a `GenericMimeError` with the message and the cause.


GenericMimeError

Represents a `HeaderNotFoundError` error with the message and the cause.


HeaderNotFoundError

Represents a `HeaderUnavailableError` with the message and the cause.


HeaderUnavailableError

Represents an `IdleTimeoutTriggeredError` with the message and the cause.


IdleTimeoutTriggeredError

Represents a `InvalidContentLengthError` error with the message and the cause.


InvalidContentLengthError

Represents an `InvalidContentTypeError` with the message and the cause.


InvalidContentTypeError

Represents a `InvalidHeaderOperationError` error with the message and the cause.


InvalidHeaderOperationError

Represents a `InvalidHeaderParamError` error with the message and the cause.


InvalidHeaderParamError

Represents a `InvalidHeaderValueError` error with the message and the cause.


InvalidHeaderValueError

Represents a `NoContentError` with the message and the cause.


NoContentError

Represents a `ParserError` with the message and the cause.


ParserError

Represents a `SerializationError` error with the message and the cause.


SerializationError

Represents a `SetHeaderError` with the message and the cause.


SetHeaderError

Represents values in `Content-Disposition` header.



Default filename for storing the body part if the receiving agent wishes to store it in an external
file


fileName

string

Indicates how the body part should be presented (`inline`, `attachment`, or as `form-data`)


disposition

Represents the field name in case of `multipart/form-data`


name

A set of parameters specified in the `attribute=value` notation


parameters

Converts the `ContentDisposition` type to a string suitable to use as the value of a corresponding MIME header.
```ballerina
string contDisposition = contentDisposition.toString();
```



toString

The `string` representation of the `ContentDisposition` object


ContentDisposition

Represents the headers and body of a message. This can be used to represent both the entity of a top level message
and an entity(body part) inside of a multipart entity.



Sets the content-type to the entity.
```ballerina
mime:InvalidContentTypeError? contentType = mimeEntity.setContentType("application/json");
```



setContentType

Content type, which needs to be set to the entity


mediaType

`()` if successful or else an `mime:InvalidContentTypeError` in case of invalid media-type


Gets the content type of the entity.
```ballerina
string contentType = mimeEntity.getContentType();
```



getContentType

Sets the content ID of the entity.
```ballerina
mimeEntity.setContentId("test-id");
```



setContentId

Content ID, which needs to be set to the entity


contentId

Gets the content ID of the entity.
```ballerina
string contentId = mimeEntity.getContentId();
```



getContentId

Sets the content length of the entity.
```ballerina
mimeEntity.setContentLength(45555);
```



setContentLength

Content length, which needs to be set to the entity


contentLength

Gets the content length of the entity.
```ballerina
int|error contentLength = mimeEntity.getContentLength();
```



getContentLength

Content length as an `int` or else an error in case of a failure


Sets the content disposition of the entity.
```ballerina
mimeEntity.setContentDisposition(contentDisposition);
```



setContentDisposition

Content disposition, which needs to be set to the entity


contentDisposition

Gets the content disposition of the entity.
```ballerina
mime:ContentDisposition contentDisposition = mimeEntity.getContentDisposition();
```



getContentDisposition

Sets the body of the entity with the given content. Note that any string value is set as `text/plain`. To send a
JSON-compatible string, set the content-type header to `application/json` or use the `setJsonPayload` method instead.
```ballerina
mimeEntity.setBody("body string");
```



setBody

Entity body can be of the type `string`,`xml`,`json`,`byte[]`,`Entity[]`, or `stream<byte[], io:Error?>`


entityBody

Sets the entity body with a given file. This method overrides any existing `content-type` headers
with the default content-type, which is `application/octet-stream`. This default value
can be overridden by passing the content type as an optional parameter.
```ballerina
mimeEntity.setFileAsEntityBody("<file path>");
```



setFileAsEntityBody

filePath

Content type to be used with the payload. This is an optional parameter.
The default value is `application/octet-stream`


contentType

Sets the entity body with the given `json` content. This method overrides any existing `content-type` headers
with the default content-type, which is `application/json`. This default value can be overridden
by passing the content type as an optional parameter.
```ballerina
mimeEntity.setJson({ "Hello": "World" });
```



setJson

JSON content, which needs to be set to the entity


jsonContent

json

Content type to be used with the payload. This is an optional parameter.
The default value is `application/json`


Extracts the JSON body from the entity.
```ballerina
json|mime:ParserError result = entity.getJson();
```



getJson

`json` data extracted from the entity body or else an `mime:ParserError` if the entity body is not a JSON


Sets the entity body with the given XML content. This method overrides any existing content-type headers
with the default content-type, which is `application/xml`. This default value can be overridden
by passing the content-type as an optional parameter.
```ballerina
mimeEntity.setXml(xml `<hello> world </hello>`);
```



setXml

XML content, which needs to be set to the entity


xmlContent

Content type to be used with the payload. This is an optional parameter.
The default value is `application/xml`


Extracts the `xml` body from the entity.
```ballerina
xml|mime:ParserError result = entity.getXml();
```



getXml

`xml` data extracted from the entity body or else an `mime:ParserError` if the entity body is not an XML


Sets the entity body with the given text content. This method overrides any existing content-type headers
with the default content-type, which is `text/plain`. This default value can be overridden
by passing the content type as an optional parameter.
```ballerina
mimeEntity.setText("Hello World");
```



setText

Text content, which needs to be set to the entity


textContent

Content type to be used with the payload. This is an optional parameter.
The default value is `text/plain`


Extracts the text body from the entity. If the entity body is not text compatible, an error is returned.
```ballerina
string|mime:ParserError result = entity.getText();
```



getText

`string` data extracted from the the entity body or else an `mime:ParserError` if the entity body is not
text compatible


Sets the entity body with the given byte[] content. This method overrides any existing `content-type` headers
with the default content-type, which is `application/octet-stream`. This default value
can be overridden by passing the content type as an optional parameter.
```ballerina
entity.setByteArray(content.toBytes());
```



setByteArray

`byte[]` content that needs to be set to the entity


blobContent

Gets the entity body as a `byte[]` from a given entity. If the entity size is considerably large, consider
using the `Entity.getByteStream()` method instead.
```ballerina
byte[]|mime:ParserError result = entity.getByteArray();
```



getByteArray

`byte[]` data extracted from the the entity body or else a `mime:ParserError` in case of
errors


Sets the entity body with the given byte stream content. This method overrides any existing content-type headers
with the default content-type, which is `application/octet-stream`. This default value
can be overridden by passing the content-type as an optional parameter.
```ballerina
entity.setByteStream(byteStream);
```



setByteStream

Byte stream, which needs to be set to the entity


byteStream

stream

Content-type to be used with the payload. This is an optional parameter.
The `application/octet-stream` is the default value


Gets the entity body as a stream of `byte[]` from a given entity.
```ballerina
stream<byte[], io:Error?>|mime:ParserError str = entity.getByteStream();
```



getByteStream

A defaultable parameter to state the size of the byte array. The default size is 8KB


arraySize

A byte stream from which the payload can be read or `mime:ParserError` in case of errors


Gets the body parts from a given entity.
```ballerina
mime:Entity[]|mime:ParserError result = multipartEntity.getBodyParts();
```



getBodyParts

An array of body parts(`Entity[]`) extracted from the entity body or else a `mime:ParserError` if the
entity body is not a set of the body parts


Gets the body parts as a byte stream from a given entity.
```ballerina
stream<byte[], io:Error?>|mime:ParserError str = multipartEntity.getBodyPartsAsStream();
```



getBodyPartsAsStream

A defaultable paramerter to state the size of the byte array. Default size is 8KB


Sets the body parts to the entity. This method overrides any existing `content-type` headers
with the default `multipart/form-data` content-type. The default `multipart/form-data` value can be overridden
by passing the content type as an optional parameter.
```ballerina
multipartEntity.setBodyParts(bodyParts, contentType);
```



setBodyParts

Body parts, which need to be set to the entity


bodyParts

Content-type to be used with the payload. This is an optional parameter.
The default value is `multipart/form-data`.


Gets the header value associated with the given header name.
```ballerina
string|mime:HeaderNotFoundError headerName = mimeEntity.getHeader(mime:CONTENT_LENGTH);
```



getHeader

headerName

Header value associated with the given header name as a `string`. If multiple header values are
present, then the first value is returned. The `HeaderNotFoundError` is returned if the header is not
found


Gets all the header values associated with the given header name.
```ballerina
string[]|mime:HeaderNotFoundError headerNames = mimeEntity.getHeaders(mime:CONTENT_TYPE);
```



getHeaders

All the header values associated with the given header name as a `string[]` or the
`HeaderNotFoundError` if the header is not found


Gets all the header names.
```ballerina
string[] headerNames = mimeEntity.getHeaderNames();
```



getHeaderNames

Adds the given header value against the given header. Panic if an illegal header is passed.
```ballerina
mimeEntity.addHeader("custom-header", "header-value");
```



addHeader

headerValue

Sets the given header value against the existing header. If a header already exists, its value is replaced
with the given header value. Panic if an illegal header is passed.
```ballerina
mimeEntity.setHeader("custom-header", "header-value");
```



setHeader

Removes the given header from the entity.
```ballerina
mimeEntity.removeHeader("custom-header");
```



removeHeader

Removes all headers associated with the entity.
```ballerina
mimeEntity.removeAllHeaders();
```


removeAllHeaders

Checks whether the requested header key exists in the header map.
```ballerina
boolean res = mimeEntity.hasHeader("custom-header");
```



hasHeader

`true` if the specified header key exists


boolean

Entity

Describes the nature of the data in the body of a MIME entity.



primaryType

A specific format of the primary-type data


subType

Identifies the semantics of a specific media type


suffix

A set of parameters specified in an `attribute=value` notation


Gets the “primaryType/subtype+suffix” combination in a `string` format.
```ballerina
string baseType = mediaType.getBaseType();
```



getBaseType

Base type as a `string` from the `MediaType` struct


Converts the media type to a `string`, which is suitable to be used as the value of a corresponding HTTP header.
```ballerina
string mediaTypeString = mediaType.toString();
```



Content type with parameters as a `string`


MediaType

Represents the `application/x-www-form-urlencoded` media type.


APPLICATION_FORM_URLENCODED

Represents the `application/json` media type.


APPLICATION_JSON

Represents the `application/octet-stream` media type.


APPLICATION_OCTET_STREAM

Represents the `application/pdf` media type.


APPLICATION_PDF

Represents the `application/soap+xml` media type.


APPLICATION_SOAP_XML

Represents the `application/svg+xml` media type.


APPLICATION_SVG_XML

Represents the `application/xhtml+xml` media type.


APPLICATION_XHTML_XML

Represents the `application/xml` media type.


APPLICATION_XML

Key name for `boundary` parameter in MediaType. This is needed for composite type media types.


BOUNDARY

Key name for `charset` parameter in MediaType. This indicates the character set of the body text.


CHARSET

Represents `content-disposition` header name.


CONTENT_DISPOSITION

CONTENT_ID

Represents `content-length` header name.


CONTENT_LENGTH

CONTENT_TYPE

Default charset to be used with MIME encoding and decoding.


DEFAULT_CHARSET

IMAGE_GIF

## Overview

This module provides a set of APIs to work with messages, which follow the Multipurpose Internet Mail Extensions 
(MIME) specification as specified in the [RFC 2045 standard](https://www.ietf.org/rfc/rfc2045.txt).

```
Entity refers to the header fields and the content of a message or a part of the body in a multipart entity. 
```

### Supported multipart types

The module supports `multipart/form-data`, `multipart/mixed`, `multipart/alternative`, `multipart/related`, and 
`multipart/parallel` as multipart content types.

### Modify and retrieve the data in an entity

This module provides functions to set and get an entity body from different kinds of message types such as XML, text, 
JSON, byte[], and body parts. Headers can be modified through functions such as `addHeader()`, `setHeader()`, 
`removeHeader()`, etc. 

### Handling large files

The entity object method `setFileAsEntityBody()` can be used to set large files as the entity body and 
is able to read it as a stream using the `getByteStream()` function.


This module provides a set of APIs to work with messages, which follow the Multipurpose Internet Mail Extensions 


Errors