Skip to content

builder

kumo.mimepart.builder()
Since: Dev Builds Only

The functionality described in this section requires a dev build of KumoMTA. You can obtain a dev build by following the instructions in the Installation section.

Returns a message builder object that can be used to build an email from an optional text, optional html and optional set of attachments. The builder takes care of phrasing the resulting mime structure in the most commonly accepted arrangement to reflect your combination of text, html and attachments.

For example, if you specify both an html and a text part, they will be wrapped up in a multipart/alternative container part. If you add attachments, then a multipart/mixed container will be created.

Available Methods

  • builder:text_plain(TEXT) - call this to set the plain text part of the message. The part is constructed as though you called kumo.mimepart.new_text_plain with the same parameters.
  • builder:text_html(HTML) - call this to set the HTML part of the message. The part is constructed as though you called kumo.mimepart.new_html with the same parameters.
  • builder:attach(CONTENT_TYPE, DATA, ATTACHMENT_OPTIONS) - call this to add an attachment. The part is constructed as though you called kumo.mimepart.new_binary with the same parameters.
  • builder:attach_part(PART) - call this to add an attachment part that you have constructed separately
  • builder:set_stable_content(true) - provided for testing purposes, when called and set to true, the generated boundaries and other automatically added headers will used fixed strings to aid in making test assertions.
  • builder:build() - finalize the message, consuming its internal state, and return the newly constructed MimePart.

Example

-- Build up an email with a couple of attachments/parts
local builder = kumo.mimepart.builder()
builder:text_plain 'Hello, plain'
builder:text_html '<b>Hello, html</b>'
builder:attach(
  'text/plain',
  'I am a plain text file with no options specified'
)
builder:attach('application/octet-stream', '\xaa\xbb', {
  file_name = 'binary.dat',
})
local root = builder:build()
print(root)

Will produce a message looking something like this; the boundary strings will vary:

Content-Type: multipart/mixed;
   boundary="mm-boundary"
Mime-Version: 1.0
Date: Tue, 1 Jul 2003 10:52:37 +0200

--mm-boundary
Content-Type: multipart/alternative;
   boundary="ma-boundary"

--ma-boundary
Content-Type: text/plain;
   charset="us-ascii"

Hello, plain
--ma-boundary
Content-Type: text/html;
   charset="us-ascii"

<b>Hello, html</b>
--ma-boundary--
--mm-boundary
Content-Type: text/plain
Content-Transfer-Encoding: base64

SSBhbSBhIHBsYWluIHRleHQgZmlsZSB3aXRoIG5vIG9wdGlvbnMgc3BlY2lmaWVk
--mm-boundary
Content-Type: application/octet-stream
Content-Transfer-Encoding: base64
Content-Disposition: attachment;
   filename="binary.dat"

qrs=
--mm-boundary--