Mailto Macro

The mailto macro is a specialization of the URL macro that adds support for defining an email link with text and augmenting it with additional metadata, such as a subject and body.

Using an attribute list, you can specify link text as well as named attributes such as id and role. Unlike other URL macros, you must add the mailto: prefix in front of the email address in order to append an attribute list.

Here’s an example of an email link with explicit link text.

mailto:join@discuss.example.org[Subscribe]

If you want to add a role to this link, you can do so by appending the role attribute after a comma.

mailto:join@discuss.example.org[Subscribe,role=email]

If the link text contains a comma, you must enclose the text in double quotes. Otherwise, the portion of the text that follows the comma will be interpreted as additional attribute list entries.

mailto:join@discuss.example.org["Click, subscribe, and participate!"]

To learn more about how the attributes are parsed, refer to attribute parsing.

Subject and body

Like with other URL macros, the first positional attribute of the email macro is the link text. If a comma is present in the text, and the text is not enclosed in quotes, or the comma comes after the closing quote, the next positional attribute is treated as the subject line.

For example, you can configure the email link to populate the subject line when the reader clicks the link as follows:

mailto:join@discuss.example.org[Subscribe,Subscribe me]

When the reader clicks the link, a conforming email client will fill in the subject line with “Subscribe me”.

If you want the body of the email to also be populated, specify the body text in the third positional argument.

mailto:join@discuss.example.org[Subscribe,Subscribe me,I want to participate.]

When the reader clicks the link, a conforming email client will fill in the body with “I want to participate.”

If you want to reuse the email address as the link text, leave the first positional attribute empty.

mailto:join@discuss.example.org[,Subscribe me,I want to participate.]

If you only want to specify a subject, leave off the body.

mailto:join@discuss.example.org[,Subscribe me]

If either the subject or body contains a comma, that value must be enclosed in double quotes.

mailto:join@discuss.example.org[Subscribe,"I want to participate, so please subscribe me"]

To learn more about how the attributes are parsed, refer to attribute parsing.