Mailto URI Scheme

Abstract

This document defines the format and handling of mailto URIs. It is a standalone document and does not rely on other specifications.

Introduction

Mailto URIs are used to specify email message header data. Mail clients use this data to generate default header values and default compose form text field values.

Sections

Syntax

A string equaling: "mailto:" + "TO hvalue" + "?" + "&-separated list of hname=hvalue pairs"

TO, SUBJECT, BODY, CC and BCC are the basic hnames that should be supported.

Everything after "mailto:" on up to (but not including) "?" (or the end of the URI if a "?" is not present) also represents a TO hvalue (where "mailto:" represents a TO hname).

All hname=hvalue pairs are optional.

"mailto:" and hnames are handled in a case-insensitive manner.

In HTML and XML markup, "&" must be represented as "&".

Note: "string" in this document refers to a sequence of 8bit unsigned characters. For the encoding, decoding and parsing steps, when dealing with strings with characters of a different type and or width, adjust the steps as necessary to conform.

Examples

Address syntax

Need to define the format for addresses.

Encoding data

Hvalues and hnames need to be percent-encoded.

  1. Let S be a string of raw utf-8 sequences.
  2. Replace all Carriage Return + Line Feed pairs (0x0D + 0x0A) in S with Line Feeds (0x0A).
  3. Replace all Carriage Returns (0x0D) in S with Line Feeds (0x0A).
  4. Let NOENCODE be the string "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789-_.!*()".
  5. Let HEXITS be the string "0123456789ABCDEF".
  6. Let I be the current position in S starting at 0.
  7. Let RET be the empty string to hold the built value.

  8. While I is less than the length of S:

    1. Let C be the character in S at position I.

    2. If C equals a Line Feed (0x0A):

      1. Append "%0D%0A" to RET.

    3. Else if C is found in NOENCODE:

      1. Append C to RET.

    4. Else:

      1. Append "%" to RET.
      2. Let CI be the 8bit unsigned value (0 to 255) that represents C.
      3. Let F1 be the value of CI >> 4.
      4. Let F2 be the value of CI & 0x0F.
      5. Let A be the character at position F1 in HEXITS.
      6. Let B be the character at position F2 in HEXITS.
      7. Append A to RET.
      8. Append B to RET.
    5. Increment I by 1.

A "+" in a mailto URI does not represent a space. It represents itself and does not need to be encoded for most clients to treat it correctly. However, "+" should be encoded to "%2B" whenever possible because the URI data might end up being used in a http webmail compose URI where if it's not encoded, it will be decoded to a space. This also means that browsers should generate spaces as "%20" instead of "+" for forms that use action="mailto:".

Just like hvalues, hnames can contain full utf-8 sequences. This allows clients to support unicode hnames if needed. For example, mailto:?%E2%88%9A=%E2%88%9A is valid in a mailto URI.

Decoding data

  1. Let S be the encoded string to decode.
  2. Let I be the current position in S, starting at 0.
  3. Let RET be the empty string to hold the built value.
  4. Let HEXITS be the string "0123456789ABCDEF".

  5. While I is less than the length of S:

    1. Let C be the character at position I.

    2. If C equals "%" and I + 2 is less than the length of s:

      1. Let F1 be the uppercase version of the character at position I + 1.
      2. Let F2 be the uppercase version of the character at position I + 2.
      3. Let A be the position of F1 in HEXITS.
      4. Let B be the position of F2 in HEXITS.

      5. If F1 or F2 was not found in HEXITS:

        1. Append C to RET.

      6. Else:

        1. Append the character represented by the 8bit unsigned value (0 to 255) of (A * 16 + B) to RET.
        2. Increment I by 2.

    3. Else:

      1. Append C to RET
    4. Increment I by 1
  6. Replace all Carriage Return + Line Feed pairs (0x0D + 0x0A) in RET with Line Feeds (0x0A).
  7. Then, replace all Carriage Returns (0x0D) in RET with Line Feeds(0x0A).

RET will be a string of raw utf-8 sequences with all newline pairs and single newlines normalized to \n.

Handling of duplicate hnames

In a mailto URI, there can be more than one hname with the same name. When a client parses a mailto URI to generate a TO, CC, BCC, SUBJECT or BODY value, the following rules should be followed.

If the client supports other address-based hnames, the TO, CC and BCC rules can be used if desired.

Duplicate hnames are allowed for use with clients that have hvalue length restrictions, but still want to support acceptence of large amounts of data for an hname. Even clients that don't have length restrictions should support duplicate hnames for compatibility.

Pre-Parsing

  1. Let S be the incoming string.
  2. Let P be an empty string to store the &-separated list of hname=hvalue pairs.

  3. If S starts with a case-insensitive "mailto:":

    1. Let SUB be the substring of S starting at and including the character at position 4 to the end of S.
    2. Replace the first ':' in SUB with '='.

    3. If one or more '?' are present in SUB:

      1. Replace only the first '?' with '&'.
    4. Assign SUB to P.

  4. Else:

    1. Fail.

Parsing

  1. Let P be the string with the &-separated list of hname=hvalue pairs.
  2. Split P by '&' into array HLIST.
  3. Let I be the current position in HLIST starting at 0.
  4. Let TO, SUBJECT, BODY, CC and BCC be empty strings to store the encoded values.

  5. While I is less than the length of HLIST:

    1. Let S be the string at position I in HLIST.
    2. Let EQ be the position of the first '=' in S.

    3. If a '=' is found in S:

      1. Let HNAME be a string representing the lowercase version of a substring of S starting at and including the character at position 0 on up to, but not including the character at position EQ.
      2. Let HVALUE be a string representing a substring of S starting at and including the character at position EQ + 1 to the end of S.

      3. If HNAME equals "to":

        1. If HVALUE is not empty:

          1. If TO is not empty:

            1. Append "%2C%20" to TO.
          2. Append HVALUE to TO.

      4. Else if HNAME equals "cc":

        1. If HVALUE is not empty:

          1. If CC is not empty:

            1. Append "%2C%20" to CC.
          2. Append HVALUE to CC.

      5. Else if HNAME equals "bcc":

        1. If HVALUE is not empty:

          1. If BCC is not empty:

            1. Append "%2C%20" to BCC.
          2. Append HVALUE to BCC.

      6. Else if HNAME equals "subject":

        1. Assign HVALUE to SUBJECT.

      7. Else if HNAME equals "body":

        1. If (HVALUE is empty and BODY is empty) equals false:

          1. If BODY is not empty:

            1. Append "%0D%0A" to BODY.
          2. Append HVALUE to BODY.
    4. Increment I by 1.
  6. Let DTO, DSUBJECT, DBODY, DCC and DBCC be strings of raw utf-8 sequences representing the decoded versions of TO, SUBJECT, BODY, CC and BCC respectively.
  7. Optionally, reencode from DTO, DSUBJECT, DBODY, DCC and DBCC to generate normalized TO, SUBJECT, BODY, CC and BCC values where:

The decoded values are what mail clients use (after converting them to the needed encoding) to fill in a compose form's text fields.

Test

mailto link

Click on the link. In your mail client's compose form, you should get the following results.

To:

Cc:

Bcc:

Subject:

Note that there may be extra lines in the body in your mail client if it has signature support.

Also note that for the TO, CC and BCC fields, user-input in most clients requires properly-escaped addresses where certain charactes are escaped with "\". However, some clients allow unescaped user-input and will, after decoding, deescape characters escaped with "\" when filling in the fields. As long as the intended headers are produced in the outgoing message, the client can use whatever user-input method that's desired.

Implementations of parsing, decoding and encoding

In MailtoURIParserPack.zip are C++, D, Java, Javascript, Perl, Python and Ruby MailtoURIParser classes that use the rules in this document.