1# Using startAbilityByType to Start an Email Application 2 3This topic describes how to open the vertical domain panel of email applications. 4> **NOTE** 5> 6> If the parameter from the initiating application is a mailto string, you are advised to [use mailto to start an email application](start-email-apps-by-mailto.md). Upon receiving the mailto string, the email application parses the string to fill in details like the sender, recipient, and email body. 7 8## Parameters on the Email Application Panel 9 10If the **type** field in **startAbilityByType** is set to **mail**, **wantParam** contains the following properties. 11 12| Name | Type | Mandatory| Description | 13| ------------------------------------- | ------------------------------------------------------------ | ------ | ------------------------------------------------------------ | 14| email | string[ ] | No | Email address of the recipient. Multiple email addresses, separated by commas (,), are supported. | 15| cc | string[ ] | No | Email address of the CC recipient. Multiple email addresses, separated by commas (,), are supported. | 16| bcc | string[ ] | No | Email address of the BCC recipient. Multiple email addresses, separated by commas (,), are supported. | 17| subject | string | No | Email subject. | 18| body | string | No | Email body. | 19| ability.params.stream | string[ ] | No | Email attachments (URI list of the attachments). | 20| ability.want.params.uriPermissionFlag | [wantConstant.Flags](../reference/apis-ability-kit/js-apis-app-ability-wantConstant.md#flags) | No | At least the read permission must be granted on the email attachments. This parameter is mandatory when **ability.params.stream** is specified.| 21| sceneType | number | No | Intent scene, which indicates the purpose of the current request. 1: Send an email. The default value is **1**. | 22 23> **NOTE** 24> 25> * Parameters of the string type displayed in the vertical domain panel of email applications must be encoded using **encodeURI**. 26> 27> * For parameters of the string[] type displayed in the vertical domain panel of email applications, all elements in the array must be encoded using **encodeURI**. 28 29## Developing a Caller Application 301. Import the module. 31 ```ts 32 import { common, wantConstant } from '@kit.AbilityKit'; 33 ``` 342. Construct parameters and call the **startAbilityByType** API. 35 36 ```ts 37 let context = getContext(this) as common.UIAbilityContext; 38 let wantParam: Record<string, Object> = { 39 'sceneType': 1, 40 'email': [encodeURI('xxx@example.com'),encodeURI('xxx@example.com')], // Email address of the recipient. Multiple values are separated by commas (,). The array content is URL encoded using encodeURI(). 41 'cc': [encodeURI('xxx@example.com'),encodeURI('xxx@example.com')], // Email address of the CC recipient. Multiple values are separated by commas (,). The array content is URL encoded using encodeURI(). 42 'bcc': [encodeURI('xxx@example.com'),encodeURI('xxx@example.com')], // Email address of the BCC recipient. Multiple values are separated by commas (,). The array content is URL encoded using encodeURI(). 43 'subject': encodeURI('Email subject'), // Email subject. The content is URL encoded using encodeURI(). 44 'body': encodeURI('Email body'), // Email body. The content is URL encoded using encodeURI(). 45 'ability.params.stream':[encodeURI('attachment uri1'),encodeURI('attachment uri2')], // Attachment URIs. Multiple values are separated by commas (,). The array content is URL encoded using encodeURI(). 46 'ability.want.params.uriPermissionFlag': wantConstant.Flags.FLAG_AUTH_READ_URI_PERMISSION 47 }; 48 let abilityStartCallback: common.AbilityStartCallback = { 49 onError: (code: number, name: string, message: string) => { 50 console.log(`onError code ${code} name: ${name} message: ${message}`); 51 }, 52 onResult: (result)=>{ 53 console.log(`onResult result: ${JSON.stringify(result)}`); 54 } 55 } 56 57 context.startAbilityByType("mail", wantParam, abilityStartCallback, 58 (err) => { 59 if (err) { 60 console.error(`startAbilityByType fail, err: ${JSON.stringify(err)}`); 61 } else { 62 console.log(`success`); 63 } 64 }); 65 ``` 66 Effect 67 68  69 70## Developing a Target Application 71 721. Add the [linkFeature](../quick-start/module-configuration-file.md#skills) attribute to **module.json5** and declare the features supported. In this way, the system can find the applications that support a specific feature from all the applications installed on the device. 73 74 | Value | Description | 75 | --------------| ------------------------- | 76 | ComposeMail | The application supports email writing. | 77 78 ```json 79 { 80 "abilities": [ 81 { 82 "skills": [ 83 { 84 "uris": [ 85 { 86 "scheme": "mailto", // It is for reference only. Ensure that the declared URI can be started by external systems. 87 "host": "", 88 "path": "", 89 "linkFeature": "ComposeMail" // Declare that the application supports email writing. 90 } 91 ] 92 } 93 ] 94 } 95 ] 96 } 97 ``` 98 992. Parse and process the parameters transferred from the panel. 100 101 ```ts 102 UIAbility.onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void 103 ``` 104 105 The **want.parameters** parameter contains the following parameters, which may be slightly different from the ones passed in by the caller. 106 107 | Name | Type | Mandatory| Description | 108 | ------- | --------- | ---- | -------------------------------------- | 109 | email | string[ ] | No | Email address of the recipient. Multiple email addresses, separated by commas (,), are supported.| 110 | cc | string[ ] | No | Email address of the CC recipient. Multiple email addresses, separated by commas (,), are supported.| 111 | bcc | string[ ] | No | Email address of the BCC recipient. Multiple email addresses, separated by commas (,), are supported.| 112 | subject | string | No | Email subject. | 113 | body | string | No | Email body. | 114 | stream | string[ ] | No | Email attachments (URI list of the attachments). | 115 116 > **NOTE** 117 > 118 > * Parameters of the string type received by the target application must be decoded using **decodeURI**. 119 > 120 > * For parameters of the string[] type received by the target application, all elements in the array must be decoded using **decodeURI**. 121 122**Sample Code** 123 124```ts 125import { AbilityConstant, UIAbility, Want } from '@kit.AbilityKit'; 126import { hilog } from '@kit.PerformanceAnalysisKit'; 127import { window } from '@kit.ArkUI'; 128 129const TAG = 'MailTarget1.EntryAbility' 130 131export default class EntryAbility extends UIAbility { 132 windowStage: window.WindowStage | null = null; 133 134 email: string[] | undefined; 135 cc: string[] | undefined; 136 bcc: string[] | undefined; 137 subject: string | undefined; 138 body: string | undefined; 139 stream: string[] | undefined; 140 141 onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void { 142 hilog.info(0x0000, TAG, `onCreate, want=${JSON.stringify(want)}`); 143 super.onCreate(want, launchParam); 144 this.parseWant(want); 145 } 146 147 onNewWant(want: Want, launchParam: AbilityConstant.LaunchParam): void { 148 hilog.info(0x0000, TAG, `onNewWant, want=${JSON.stringify(want)}`); 149 super.onNewWant(want, launchParam); 150 this.parseWant(want); 151 if (!this.windowStage) { 152 hilog.error(0x0000, TAG, 'windowStage is null'); 153 this.context.terminateSelf(); 154 return; 155 } 156 this.loadPage(this.windowStage); 157 } 158 159 private parseWant(want: Want): void { 160 this.email = this.decodeStringArr(want.parameters?.email as string[]); 161 this.cc = this.decodeStringArr(want.parameters?.cc as string[]); 162 this.bcc = this.decodeStringArr(want.parameters?.bcc as string[]); 163 this.subject = decodeURI(want.parameters?.subject as string); // Use decodeURI() to decode the URL of the email subject. Other fields are processed in the same way. 164 this.body = decodeURI(want.parameters?.body as string); // Use decodeURI() to decode the URL of the email body. Other fields are processed in the same way. 165 this.stream = this.decodeStringArr(want.parameters?.stream as string[]); 166 } 167 168 // Use decodeURI() to decode the content in the string array. 169 private decodeStringArr(source: string[] | undefined): string[] { 170 let target: string[] = []; 171 source?.forEach(e => { 172 target.push(decodeURI(e)); 173 }) 174 return target; 175 } 176 177 private loadPage(windowStage: window.WindowStage): void { 178 const storage: LocalStorage = new LocalStorage({ 179 "email": this.email, 180 "cc": this.cc, 181 "bcc": this.bcc, 182 "subject": this.subject, 183 "body": this.body, 184 "stream": this.stream 185 } as Record<string, Object>); 186 187 windowStage.loadContent('pages/ComposeMailPage', storage); 188 189 } 190 191 onDestroy(): void { 192 hilog.info(0x0000, TAG, `onDestroy`); 193 } 194 195 onWindowStageCreate(windowStage: window.WindowStage): void { 196 hilog.info(0x0000, TAG, `onWindowStageCreate`); 197 this.windowStage = windowStage; 198 this.loadPage(this.windowStage); 199 } 200 201 onWindowStageDestroy(): void { 202 hilog.info(0x0000, TAG, `onWindowStageDestroy`); 203 } 204 205 onForeground(): void { 206 hilog.info(0x0000, TAG, `onForeground`); 207 } 208 209 onBackground(): void { 210 hilog.info(0x0000, TAG, `onBackground`); 211 } 212} 213``` 214
