Module Netsendmail

module Netsendmail: sig .. end

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_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 * Netmime_string.s_param) list ->
       ?container_type:string * (string * Netmime_string.s_param) list ->
       ?attachments:Netmime.complex_mime_message list ->
       to_addrs:(string * string) list ->
       subject:string -> string -> Netmime.complex_mime_message

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_types 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 * Netmime_string.s_param) list ->
       content_type:string * (string * Netmime_string.s_param) list ->
       Netmime.mime_body -> Netmime.complex_mime_message

 compose ...
    ~attachments:[ wrap_attachment
                      ~content_type:("audio/wav", [])
                      (new file_mime_body "music.wav") ]
 

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

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 * Netmime_string.s_param) list ->
       ?content_id:string ->
       ?content_description:string ->
       ?content_location:string ->
       ?content_disposition:string * (string * Netmime_string.s_param) list ->
       Netmime.complex_mime_message list -> Netmime.complex_mime_message

val create_address_list_tokens : ?in_charset:Netconversion.encoding ->
       ?out_charset:Netconversion.encoding ->
       (string * string) list -> Netmime_string.s_token list

 let sval = create_address_list_tokens ["Stolpmann, Gerd",
                                        "gerd@gerd-stolpmann.de"] in
 header # update_field "to" (format_field_value "to" sval)
 

val create_text_tokens : ?in_charset:Netconversion.encoding ->
       ?out_charset:Netconversion.encoding -> string -> Netmime_string.s_token list

 let sval = create_text_tokens "I have to say something" in
 header # update_field "subject" (format_field_value "subject" sval)
 

val format_field_value : string -> Netmime_string.s_token list -> string

Sending Messages

val sendmail : ?mailer:string -> ?crlf:bool -> Netmime.complex_mime_message -> unit