• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# Using mailto to Start an Email Application
2
3## When to Use
4
5You can create hyperlinks that link to email addresses through mailto, so that users can easily access email clients by touching the hyperlinks present within websites or applications. You can also preset the recipient, subject, and body of the email in the mailto: fields to save the time when composing emails.
6
7Typical development scenarios are as follows:
8
9- On websites:
10    - When browsing product pages on a shopping website, users can touch a **Contact Us** button, which triggers the default email client with the customer service email pre-filled as the recipient and the subject line set to inquire about the product.
11    - On job posting pages, touching an **Apply for Job** button opens an email client with the recruitment email address pre-filled, the subject line set to "Request for a Specific Position," and the body possibly pre-populated with a request template.
12- Within applications:
13    - In a mobile application, touching a **Feedback** button may cause the application to activate the system's default email client, with the feedback email address and issue details preset.
14    - In a mobile application, when users touch a **Share via email** button, the application can use the mailto protocol to initiate the email client, pre-populating the subject and body of the email.
15> **NOTE**
16> - To start an email application through mailto, the initiating application must first format the string according to the mailto protocol and then use this method to launch the email application. The email application parses the mailto string to populate fields like the sender, recipient, and email body.
17> - If the initiating application already has details such as the sender, recipient, and email body, you are advised to [use startAbilityByType to start an email application](start-email-apps.md).
18
19## Format of mailto
20
21The standard mailto format is as follows:
22
23```
24mailto:someone@example.com?key1=value1&key2=value2
25```
26
27+ **mailto:**: mailto scheme, which is mandatory.
28+ **someone@example.com**: recipient address, which is optional. If there are multiple addresses, separate them with commas (,).
29+ **?**: start character of the email header declaration. If email header parameters are contained, this parameter is mandatory.
30+ **key-value**: email header parameters. For details, see the following table.
31
32  | Email Header Parameter| Description| Data Type| Mandatory|
33  | --- | --- | --- | --- |
34  | subject | Email subject.| string | No|
35  | body | Email body.| string | No|
36  | cc| Copy-to person. Use commas (,) to separate multiple recipients.| string | No|
37  | bcc| Bcc recipient. Use commas (,) to separate multiple recipients.| string | No|
38
39## Developing a Caller Application
40
41### On Websites
42
43Hyperlinks on web pages must comply with the mailto protocol. Example:
44
45
46```
47<a href="mailto:support@example.com?subject=Product Inquiry&body=I am interested in...">Contact Us</a>
48```
49Replace the email address with the actual one, and configure the email content as required.
50
51### Within Applications
52
53Pass the mailto string to the **uri** parameter. In the application, the context can be obtained through **getContext (this)** for a page and through **this.context** for an ability.
54
55```ts
56@Entry
57@Component
58struct Index {
59
60  build() {
61    Column() {
62      Button('Feedback')
63        .onClick(() => {
64          let ctx = getContext(this) as common.UIAbilityContext;
65          ctx.startAbility({
66            action: 'ohos.want.action.sendToData',
67            uri: 'mailto:feedback@example.com?subject=App Feedback&body=Please describe your feedback here...'
68          })
69
70        })
71    }
72  }
73}
74```
75
76
77
78## Developing a Target Application
79
801. To be started by other applications in mailto mode, an application must declare its mailto configuration in the [module.json5 file](../quick-start/module-configuration-file.md).
81
82    ```json
83    {
84      "module": {
85        // ...
86        "abilities": [
87          {
88            // ...
89            "skills": [
90              {
91              "actions": [
92                  'ohos.want.action.sendToData'
93                ],
94                "uris": [
95                  {
96                    "scheme": "mailto",
97                    // linkFeature is used to start a vertical domain panel.
98                    "linkFeature": 'ComposeMail'
99                  }
100                ]
101              }
102            ]
103          }
104        ]
105      }
106    }
107    ```
108
1092. The target application obtains the **uri** parameter from the code for parsing.
110
111    ```ts
112    export default class EntryAbility extends UIAbility {
113      onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {
114        // Callback of the application cold start lifecycle, where other services are processed.
115        parseMailto(want);
116      }
117
118      onNewWant(want: Want, launchParam: AbilityConstant.LaunchParam): void {
119        // Callback of the application hot start lifecycle, where other services are processed.
120        parseMailto(want);
121      }
122
123      public parseMailto(want: Want) {
124        const uri = want?.uri;
125        if (!uri || uri.length <= 0) {
126          return;
127        }
128        // Start to parse mailto...
129      }
130    }
131
132    ```
133