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