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> 17> - 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. 18> - 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). 19 20## Format of mailto 21 22The standard mailto format is as follows: 23 24``` 25mailto:someone@example.com?key1=value1&key2=value2 26``` 27 28+ **mailto:**: mailto scheme, which is mandatory. 29+ **someone@example.com**: recipient address, which is optional. If there are multiple addresses, separate them with commas (,). 30+ **?**: start character of the email header declaration. If email header parameters are contained, this parameter is mandatory. 31+ **key-value**: email header parameters. For details, see the following table. 32 33 | Email Header Parameter| Description| Data Type| Mandatory| 34 | --- | --- | --- | --- | 35 | subject | Email subject.| string | No| 36 | body | Email body.| string | No| 37 | cc| Copy-to person. Use commas (,) to separate multiple recipients.| string | No| 38 | bcc| Bcc recipient. Use commas (,) to separate multiple recipients.| string | No| 39 40Handling Special Characters 41 42Special characters (for example, @ ? = &) in email header parameter values can lead to configuration issues. To avoid this, replace these characters with their ASCII codes, preceded by a percent sign (%). 43 44Refer to the following for the mapping between common symbols and ASCII codes: 45 46|Special Character| : | @ | ? | = | & | # | $ | 47|---- | ---- | ---- | ---- | ---- | ---- | ---- | ---- | 48|ASCII Code| %3A | %40 | %3F | %3D | %26 | %23 | %24 | 49 50## Developing a Caller Application 51 52### On Websites 53 54Hyperlinks on web pages must comply with the mailto protocol. Example: 55 56 57``` 58<a href="mailto:support@example.com?subject=Product Inquiry&body=I am interested in...">Contact Us</a> 59``` 60Replace the email address with the actual one, and configure the email content as required. 61 62### Within Applications 63 64Pass the mailto string to the **uri** parameter. In the application, the context can be obtained through **getHostContext()** for a page and through **this.context** for an ability. 65 66```ts 67import { common } from '@kit.AbilityKit'; 68 69@Entry 70@Component 71struct Index { 72 build() { 73 Column() { 74 Button('Feedback') 75 .onClick(() => { 76 let ctx = this.getUIContext().getHostContext() as common.UIAbilityContext; 77 ctx.startAbility({ 78 action: 'ohos.want.action.sendToData', 79 uri: 'mailto:feedback@example.com?subject=App Feedback&body=Please describe your feedback here...' 80 }) 81 }) 82 } 83 } 84} 85``` 86 87 88## Developing a Target Application 89 901. 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). 91 92 ```json 93 { 94 "module": { 95 // ... 96 "abilities": [ 97 { 98 // ... 99 "skills": [ 100 { 101 "actions": [ 102 'ohos.want.action.sendToData' 103 ], 104 "uris": [ 105 { 106 "scheme": "mailto", 107 // linkFeature is used to start a vertical domain panel. 108 "linkFeature": 'ComposeMail' 109 } 110 ] 111 } 112 ] 113 } 114 ] 115 } 116 } 117 ``` 118 1192. The target application obtains the **uri** parameter from the code for parsing. 120 121 ```ts 122 export default class EntryAbility extends UIAbility { 123 onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void { 124 // Callback of the application cold start lifecycle, where other services are processed. 125 parseMailto(want); 126 } 127 128 onNewWant(want: Want, launchParam: AbilityConstant.LaunchParam): void { 129 // Callback of the application hot start lifecycle, where other services are processed. 130 parseMailto(want); 131 } 132 133 public parseMailto(want: Want) { 134 const uri = want?.uri; 135 if (!uri || uri.length <= 0) { 136 return; 137 } 138 // Start to parse mailto... 139 } 140 } 141 142 ``` 143