(* $Id: netsendmail.mli 1003 2006-09-24 15:17:15Z gerd $
* ----------------------------------------------------------------------
*
*)
(** Functions to compose and send electronic mails
*
* {b Contents}
*
* - {!Netsendmail.composing}
* - {!Netsendmail.sending}
*
* The tutorial has been moved to {!Netsendmail_tut}.
*)
(** {1:composing Composing Messages}
*
* The core function is {!Netsendmail.compose} generating a MIME mail.
* The mail can be sent with {!Netsendmail.sendmail}, written to an
* object channel with {!Netmime.write_mime_message}, or postprocessed
* by a user function.
*
* The call to [compose] can be as easy as
*
* {[ compose ~from_addr:("me", "me\@domain.net")
* ~to_addr:("you", "you\@domain.com")
* ~subject:"I have a message for you"
* "Hello, this is my message!\n"
* ]}
*
* This call generates the message as {!Netmime.complex_mime_message},
* and can be directly sent with {!Netsendmail.sendmail}.
*
* The [compose] function is the simplified interface; alternatively one
* can also generate the mail by calling {!Netsendmail.wrap_mail},
* {!Netsendmail.wrap_parts}, and {!Netsendmail.wrap_attachment}, getting
* more fine-grained control of certain options.
*)
val compose :
?in_charset:Netconversion.encoding ->
?out_charset:Netconversion.encoding ->
?from_addr:(string * string) ->
?cc_addrs:(string * string) list ->
?bcc_addrs:(string * string) list ->
?content_type:(string * (string * Mimestring.s_param) list) ->
?container_type:(string * (string * Mimestring.s_param) list) ->
?attachments:Netmime.complex_mime_message list ->
to_addrs:(string * string) list ->
subject:string ->
(* text:*) string ->
Netmime.complex_mime_message
(** Composes a mail message with a main text, and optionally
* a number of attachments.
*
* The addresses [from_addr], [to_addrs], [cc_addrs], and [bcc_addrs] are
* passed as pairs [(human_readable,formal)] where
* [human_readable] is an arbitrary printable string identifying the
* sender/receiver, and where [formal] is the RFC-822 mailbox specification.
* An example is [("Stolpmann, Gerd", "gerd\@gerd-stolpmann.de")].
*
* The [subject] can be any text.
*
* The anonymous [string] argument is the main text of the mail.
*
* The resulting message is always a correct MIME message.
*
* @param in_charset All passed texts (except the formal addresses) must
* be encoded in [in_charset]. Default: [`Enc_iso88591].
* As another exception, setting [content_type] explicitly prevents
* the main text from being converted, and [in_charset] does not
* have a meaning for the main text.
* @param out_charset The encoded words in the generated header fields,
* if necessary, and the main text are encoded in [out_charset].
* Default: [`Enc_iso88591].
* It is required that [out_charset] is ASCII-compatible.
* As a special rule, setting [content_type] explicitly prevents
* the main text from being converted to [out_charset].
* @param content_type The content type of the main text. The list is
* the list of parameters attached
* to the type, e.g. [("text/plain", ["charset", mk_param "ISO-8859-1"])]
* (see {!Mimestring.mk_param}). When this argument is set,
* the main text is no longer converted to [out_charset].
* By default, when this argument is missing, the main text is
* converted from [in_charset] to [out_charset], and the
* content type becomes ["text/plain; charset=<out_charset>"].
* @param container_type The content type of the container wrapping the
* main text and the attachment into one entity
* (only used if [attachments] are present). This
* defaults to [("multipart/mixed", [])]. This must be either a
* "multipart" or "message" type.
* @param attachments An optional list of attachments. Should be generated
* with [wrap_attachment].
*)
(** {b Character Set Conversion}
*
* The impact of [in_charset] and [out_charset] on the generated mail
* is not very obvious. The charset arguments may have an effect on
* the mail header and the mail body.
*
* The mail header can only be composed of ASCII characters (7 bit).
* To circumvent this restriction the MIME standard specifies a special
* format, the so-called encoded words. These may only be used in some
* places, and [compose] knows where: In the subject, and the non-formal
* part of mail addresses. The [out_charset] is the character set
* used in the generated mail. The [in_charset] is the character set
* the strings are encoded you pass to [compose]. It is a good idea
* to have [in_charset = out_charset], or at least choose [out_charset]
* as a superset of [in_charset], because this ensures that the character
* set conversion succeeds.
*
* If the mail header does not make use of the additional non-ASCII
* characters, the encoded words will be avoided.
*
* The mail body is only subject of character set conversion if
* the [content_type] is {b not} passed to [compose]. In this case,
* the function sets it to [text/plain], and converts the message
* from [in_charset] to [out_charset].
*
* {b Adding Attachments}
*
* To generate the attachments, call {!Netsendmail.wrap_attachment}, e.g.
*
* {[ compose ...
* ~attachments:[ wrap_attachment
* ~content_type:("application/octet-stream", [])
* (new Netmime.file_mime_body "file.tar.gz") ]
* ]}
*
* There
* are a number of kinds of attaching files, identified by [container_type].
* The default is [multipart/mixed], meaning that the parts of the mail are
* mixed messages and files. One can give a hint whether to display
* the parts directly in the mailer program (so-called inline attachments),
* or whether to suggest that the file is saved to disk ("real"
* attachments). This hint is contained in the [Content-disposition]
* header, see [wrap_attachment] how to set it.
*
* For a discusion of the other [container_type]s see the
* {!Netsendmail.tutorial} at the end of this document.
*)
val wrap_attachment :
?in_charset:Netconversion.encoding ->
?out_charset:Netconversion.encoding ->
?content_id:string ->
?content_description:string ->
?content_location:string ->
?content_disposition:(string * (string * Mimestring.s_param) list) ->
content_type:(string * (string * Mimestring.s_param) list) ->
Netmime.mime_body ->
Netmime.complex_mime_message
(** Generates a header for the [mime_body]. The returned value
* is intended to be used as input for the [attachments] argument
* of the [compose] function:
*
* {[
* compose ...
* ~attachments:[ wrap_attachment
* ~content_type:("audio/wav", [])
* (new file_mime_body "music.wav") ]
* ]}
*
* The header contains at least the [Content-type] and the
* [Content-transfer-encoding] fields. The latter is currently
* always ["base64"], but it is possible that the function is
* changed in the future to also generate ["quoted-printable"]
* when applicable.
*
* @param in_charset The encoding of the [content_description] argument.
* Default: [`Enc_iso88591].
* @param out_charset The encoding of the generated [Content-Description]
* header. Default: [`Enc_iso88591].
* @param content_type Specifies the content type with main
* type and list of parameters. Example:
* [ ("text/plain", ["charset", Mimestring.mk_param "ISO-8859-1" ]) ]
* (see {!Mimestring.mk_param})
* @param content_disposition Optionally sets the [Content-disposition]
* header. Frequent values are
* - [ ("inline", []) ]: Indicates that the attachment is displayed
* together with the main text
* - [ ("attachment", ["filename", Mimestring.mk_param fn]) ]: Indicates
* that the attachment should be stored onto the disk. The
* parameter [fn] is the suggested file name. Note that [fn]
* should only consist of ASCII characters unless the [charset]
* argument of [mk_param] is set to a different character encoding.
* @param content_id Optionally sets the [Content-ID] header field.
* The passed string is the ID value without the embracing angle
* brackets. The [Content-ID] can be used to refer to the attachment
* from other parts of the mail, e.g. in [multipart/related] mails
* HTML documents can include hyperlinks to attachments using the
* URL syntax [cid:ID] where [ID] is the ID value.
* @param content_description The [Content-Description] header
* @param content_location The [Content-Location] header. This must be
* a valid URL, only composed of 7 bit characters, and with escaped
