cowboy/guide/multipart_intro.md

Introduction to multipart
=========================

Multipart originates from MIME, an Internet standard that
extends the format of emails. Multipart messages are a
container for parts of any content-type.

For example, a multipart message may have a part
containing text and a second part containing an
image. This is what allows you to attach files
to emails.

In the context of HTTP, multipart is most often used
with the `multipart/form-data` content-type. This is
the content-type you have to use when you want browsers
to be allowed to upload files through HTML forms.

Multipart is of course not required for uploading
files, it is only required when you want to do so
through HTML forms.

Structure
---------

A multipart message is a list of parts. Parts may
contain either a multipart message or a non-multipart
content-type. This allows parts to be arranged in a
tree structure, although this is a rare case as far
as the Web is concerned.

Form-data
---------

In the normal case, when a form is submitted, the
browser will use the `application/x-www-form-urlencoded`
content-type. This type is just a list of keys and
values and is therefore not fit for uploading files.

That's where the `multipart/form-data` content-type
comes in. When the form is configured to use this
content-type, the browser will use one part of the
message for each form field. This means that a file
input field will be sent in its own part, but the
same applies to all other kinds of fields.

A form with a text input, a file input and a select
choice box will result in a multipart message with
three parts, one for each field.

The browser does its best to determine the content-type
of the files it sends this way, but you should not
rely on it for determining the contents of the file.
Proper investigation of the contents is recommended.