email-macro.adoc 1.53 KB
Newer Older
1
= Mailto Macro
2

3
The mailto macro is a specialization of the URL macro that adds support for augmenting the email link with additional metadata, namely a subject and body.
4
5
6

== Subject and body

7
Like with other URL macros, the first positional attribute of the email macro is the link text.
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
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 subject line.

For example, you can configure the email link to prepopulate the subject line when the reader clicks the link using the following syntax:

[source]
----
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 also want the body of the email to be prepopulated, specify that text in the third positional argument.

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

When the reader clicks the link, a conforming email client will fill in the body with "I want to join".

28
If you want to leave the link text blank (so it falls back to the email address), start the attribute list with a comma so as to leave a blank slot for it.
29
30
31
32
33
34

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

35
If either the link text, subject, or body contains a comma, that value must be enclosed in double quotes.
36
To learn more about how the attributes are parsed, refer to xref:link-macro-attribute-parsing.adoc[attribute parsing].