module Netsendmail:Functions to compose and send electronic mailssig
..end
Contents
The tutorial has been moved to
Netsendmail_tut
.
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_addrs:["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 -> string -> Netmime.complex_mime_message
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.
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.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
.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>"
.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.attachments
: An optional list of attachments. Should be generated
with wrap_attachment
.
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 not passed to compose
. In this case,
the function sets it to text/plain
, and converts the message
from in_charset
to out_charset
.
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
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.
in_charset
: The encoding of the content_description
argument.
Default: `Enc_iso88591
.out_charset
: The encoding of the generated Content-Description
header. Default: `Enc_iso88591
.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.content_description
: The Content-Description
headercontent_location
: The Content-Location
header. This must be
a valid URL, only composed of 7 bit characters, and with escaped
unsafe characterscontent_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.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
)val wrap_mail : ?in_charset:Netconversion.encoding ->
?out_charset:Netconversion.encoding ->
?from_addr:string * string ->
?cc_addrs:(string * string) list ->
?bcc_addrs:(string * string) list ->
to_addrs:(string * string) list ->
subject:string ->
Netmime.complex_mime_message -> Netmime.complex_mime_message
The arguments are like in Netsendmail.compose
.
The input message should have at least a Content-type
header,
but this is not enforced.
Use this function as an alternative to Netsendmail.compose
,
if the message is already available as complex_mime_message
,
e.g. to re-send a parsed mail message to a new destination.
Note that mails generated by wrap_mail
always appear as new mails,
not as forwarded or replied mails. In order to do the latter a different
way of processing the message is needed.
val wrap_parts : ?in_charset:Netconversion.encoding ->
?out_charset:Netconversion.encoding ->
?content_type:string * (string * Mimestring.s_param) list ->
?content_id:string ->
?content_description:string ->
?content_location:string ->
?content_disposition:string * (string * Mimestring.s_param) list ->
Netmime.complex_mime_message list -> Netmime.complex_mime_message
in_charset
: The encoding of the content_description
argument.
Default: `Enc_iso88591
.out_charset
: The encoding of the generated Content-Description
header. Default: `Enc_iso88591
.content_type
: The Content-Type
header. Default: multipart/mixedcontent_id
: The Content-ID
header, without the angle bracketscontent_description
: The Content-Description
headercontent_location
: The Content-Location
header. This must be
a valid URL, only composed of 7 bit characters, and with escaped
unsafe characterscontent_disposition
: The Content-Disposition
headerval create_address_list_tokens : ?in_charset:Netconversion.encoding ->
?out_charset:Netconversion.encoding ->
(string * string) list -> Mimestring.s_token list
s_token
s representing email addresses as
structured value. The addresses are passed as list of pairs
(human_readable, formal)
as in the compose
function above.
The returned structured field value can be formatted and filled
into a mail header. For example, to set the "To" header to
"Stolpmann, Gerd" <gerd@gerd-stolpmann.de>
use
let sval = create_address_list_tokens ["Stolpmann, Gerd",
"gerd@gerd-stolpmann.de"] in
header # update_field "to" (format_field_value "to" sval)
This ensures that the field is correctly quoted, that appropriate
encodings are applied and that long values are folded into several
lines.
in_charset
: The character encoding used for human_readable
.
Defaults to `Enc_iso88591
.out_charset
: The character encoding used in the generated
encoded word. This encoding must be ASCII-compatible. Defaults to
`Enc_iso88591
.val create_text_tokens : ?in_charset:Netconversion.encoding ->
?out_charset:Netconversion.encoding -> string -> Mimestring.s_token list
s_token
s representing an informal text
as structured value. The text is passed as simple string.
The returned structured field value can be formatted and filled
into a mail header. For example, to set the "Subject" header to
"I have to say something"
, use
let sval = create_text_tokens "I have to say something" in
header # update_field "subject" (format_field_value "subject" sval)
This ensures that the field is correctly quoted, that appropriate
encodings are applied and that long values are folded into several
lines.
in_charset
: The character encoding used for the input string.
Defaults to `Enc_iso88591
.out_charset
: The character encoding used in the generated
encoded words. This encoding must be ASCII-compatible. Defaults to
`Enc_iso88591
.val format_field_value : string -> Mimestring.s_token list -> string
sval
, an s_token list
, into the header field name
,
call
header # update_field name (format_field_value name sval)
The field value is folded into several lines, if necessary.
val sendmail : ?mailer:string -> ?crlf:bool -> Netmime.complex_mime_message -> unit
The mailer program is the command passed as mailer
, which is by
default a reasonable compile-time setting.
With crlf
one can determine the EOL convention for the message piped to
the mailer program: If crlf
, CR/LF is used, if not crlf
, only LF is
used. The default is false
for Unix systems.