-
Notifications
You must be signed in to change notification settings - Fork 63
/
office.mailbox.yml
1756 lines (1246 loc) · 70.8 KB
/
office.mailbox.yml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
### YamlMime:TSType
name: Office.Mailbox
uid: 'outlook!Office.Mailbox:interface'
package: outlook!
fullName: Office.Mailbox
summary: |-
Provides access to the Microsoft Outlook add-in object model.
Key properties:
- `diagnostics`<!-- -->: Provides diagnostic information to an Outlook add-in.
- `item`<!-- -->: Provides methods and properties for accessing a message or appointment in an Outlook add-in.
- `userProfile`<!-- -->: Provides information about the user in an Outlook add-in.
remarks: >-
**[Minimum permission
level](https://learn.microsoft.com/office/dev/add-ins/outlook/understanding-outlook-add-in-permissions)<!-- -->**:
**restricted**
**[Applicable Outlook
mode](https://learn.microsoft.com/office/dev/add-ins/outlook/outlook-add-ins-overview#extension-points)<!-- -->**:
Compose or Read
isPreview: false
isDeprecated: false
type: interface
properties:
- name: diagnostics
uid: 'outlook!Office.Mailbox#diagnostics:member'
package: outlook!
fullName: diagnostics
summary: >-
Provides diagnostic information to an Outlook add-in.
Contains the following members.
- `hostName` (string): A string that represents the name of the Office application. It should be one of the
following values: `Outlook`<!-- -->, `OutlookWebApp`<!-- -->, `OutlookIOS`<!-- -->, or `OutlookAndroid`<!-- -->.
**Note**: The "Outlook" value is returned for Outlook on desktop clients (i.e., Windows and Mac).
- `hostVersion` (string): A string that represents the version of either the Office application or the Exchange
Server (e.g., "15.0.468.0"). If the mail add-in is running in Outlook on desktop or on mobile clients, the
`hostVersion` property returns the version of the application, Outlook. In Outlook on the web, the property
returns the version of the Exchange Server.
- `OWAView` (`MailboxEnums.OWAView` or string): An enum (or string literal) that represents the current view of
Outlook on the web. If the application is not Outlook on the web, then accessing this property results in
undefined. Outlook on the web has three views (`OneColumn` - displayed when the screen is narrow, `TwoColumns` -
displayed when the screen is wider, and `ThreeColumns` - displayed when the screen is wide) that correspond to the
width of the screen and the window, and the number of columns that can be displayed.
More information is under [Office.Diagnostics](xref:outlook!Office.Diagnostics:interface)<!-- -->.
remarks: >-
**[Minimum permission
level](https://learn.microsoft.com/office/dev/add-ins/outlook/understanding-outlook-add-in-permissions)<!--
-->**: **read item**
**[Applicable Outlook
mode](https://learn.microsoft.com/office/dev/add-ins/outlook/outlook-add-ins-overview#extension-points)<!--
-->**: Compose or Read
Starting with Mailbox requirement set 1.5, you can also use the
[Office.context.diagnostics](https://learn.microsoft.com/javascript/api/office/office.context?view=outlook-js-1.5&preserve-view=true#office-office-context-diagnostics-member)
property to get similar information.
#### Examples
```TypeScript
// Link to full sample:
https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/90-other-item-apis/get-diagnostic-information.yaml
// This function gets a mailbox's diagnostic information, such as Outlook client and version, and logs it to the
console.
const diagnostics = Office.context.mailbox.diagnostics;
console.log(`Client application: ${diagnostics.hostName}`);
console.log(`Client version: ${diagnostics.hostVersion}`);
switch (diagnostics.OWAView) {
case undefined:
console.log("Current view (Outlook on the web only): Not applicable. An Outlook desktop client is in use.");
break;
case Office.MailboxEnums.OWAView.OneColumnNarrow:
console.log("Current view (Outlook on the web only): Viewed from an older generation mobile phone");
break;
case Office.MailboxEnums.OWAView.OneColumn:
console.log("Current view (Outlook on the web only): Viewed from a newer generation mobile phone");
break;
case Office.MailboxEnums.OWAView.TwoColumns:
console.log("Current view (Outlook on the web only): Viewed from a tablet");
break;
case Office.MailboxEnums.OWAView.ThreeColumns:
console.log("Current view (Outlook on the web only): Viewed from a desktop computer");
break;
}
```
isPreview: false
isDeprecated: false
syntax:
content: 'diagnostics: Diagnostics;'
return:
type: '<xref uid="outlook!Office.Diagnostics:interface" />'
- name: ewsUrl
uid: 'outlook!Office.Mailbox#ewsUrl:member'
package: outlook!
fullName: ewsUrl
summary: Gets the URL of the Exchange Web Services (EWS) endpoint for this email account.
remarks: >-
\[ [API set: Mailbox 1.1](/javascript/api/requirement-sets/outlook/outlook-api-requirement-sets) \]
**[Minimum permission
level](https://learn.microsoft.com/office/dev/add-ins/outlook/understanding-outlook-add-in-permissions)<!--
-->**: **read item**
**[Applicable Outlook
mode](https://learn.microsoft.com/office/dev/add-ins/outlook/outlook-add-ins-overview#extension-points)<!--
-->**: Compose or Read
**Important**:
- Your app must have the **read item** permission specified in its manifest to call the `ewsUrl` member in
read mode.
- In compose mode, you must call the `saveAsync` method before you can use the `ewsUrl` member. Your app must have
**read/write item** permissions to call the `saveAsync` method.
- This property isn't supported in Outlook on Android or on iOS. For more information on supported APIs in Outlook
mobile, see [Outlook JavaScript APIs supported in Outlook on mobile
devices](https://learn.microsoft.com/office/dev/add-ins/outlook/outlook-mobile-apis)<!-- -->.
- The `ewsUrl` value can be used by a remote service to make EWS calls to the user's mailbox. For example, you can
create a remote service to [get attachments from the selected
item](https://learn.microsoft.com/office/dev/add-ins/outlook/get-attachments-of-an-outlook-item)<!-- -->.
#### Examples
```TypeScript
// Link to full sample:
https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/85-tokens-and-service-calls/ids-and-urls.yaml
console.log("EWS URL: " + Office.context.mailbox.ewsUrl);
const ewsId = Office.context.mailbox.item.itemId;
console.log("EWS item ID: " + Office.context.mailbox.item.itemId);
console.log("REST URL: " + Office.context.mailbox.restUrl);
const restId = Office.context.mailbox.convertToRestId(ewsId, Office.MailboxEnums.RestVersion.v2_0);
console.log("REST item ID: " + restId);
const ewsId2 = Office.context.mailbox.convertToEwsId(restId, Office.MailboxEnums.RestVersion.v2_0);
console.log("EWS ID (from REST ID): " + ewsId2);
```
isPreview: false
isDeprecated: false
syntax:
content: 'ewsUrl: string;'
return:
type: string
- name: item
uid: 'outlook!Office.Mailbox#item:member'
package: outlook!
fullName: item
summary: >-
The mailbox item. Depending on the context in which the add-in opened, the item type may vary. If you want to see
IntelliSense for only a specific type or mode, cast this item to one of the following:
[MessageCompose](xref:outlook!Office.MessageCompose:interface)<!-- -->,
[MessageRead](xref:outlook!Office.MessageRead:interface)<!-- -->,
[AppointmentCompose](xref:outlook!Office.AppointmentCompose:interface)<!-- -->,
[AppointmentRead](xref:outlook!Office.AppointmentRead:interface)
**Important**: `item` can be null if your add-in supports pinning the task pane. For details on how to handle,
see [Implement a pinnable task pane in
Outlook](https://learn.microsoft.com/office/dev/add-ins/outlook/pinnable-taskpane#implement-the-event-handler)<!--
-->.
remarks: ''
isPreview: false
isDeprecated: false
syntax:
content: >-
item?: Item & ItemCompose & ItemRead & Message & MessageCompose & MessageRead & Appointment & AppointmentCompose
& AppointmentRead;
return:
type: >-
<xref uid="outlook!Office.Item:interface" /> & <xref uid="outlook!Office.ItemCompose:interface" /> & <xref
uid="outlook!Office.ItemRead:interface" /> & <xref uid="outlook!Office.Message:interface" /> & <xref
uid="outlook!Office.MessageCompose:interface" /> & <xref uid="outlook!Office.MessageRead:interface" /> & <xref
uid="outlook!Office.Appointment:interface" /> & <xref uid="outlook!Office.AppointmentCompose:interface" /> &
<xref uid="outlook!Office.AppointmentRead:interface" />
- name: restUrl
uid: 'outlook!Office.Mailbox#restUrl:member'
package: outlook!
fullName: restUrl
summary: >-
Gets the URL of the REST endpoint for this email account.
Your app must have the **read item** permission specified in its manifest to call the `restUrl` member in read
mode.
In compose mode you must call the `saveAsync` method before you can use the `restUrl` member. Your app must have
**read/write item** permissions to call the `saveAsync` method.
However, in delegate or shared scenarios, you should instead use the `targetRestUrl` property of the
[SharedProperties](https://learn.microsoft.com/javascript/api/outlook/office.sharedproperties?view=outlook-js-1.8)
object (introduced in requirement set 1.8). For more information, see the [delegate
access](https://learn.microsoft.com/office/dev/add-ins/outlook/delegate-access) article.
remarks: >-
\[ [API set: Mailbox 1.5](/javascript/api/requirement-sets/outlook/outlook-api-requirement-sets) \]
**[Minimum permission
level](https://learn.microsoft.com/office/dev/add-ins/outlook/understanding-outlook-add-in-permissions)<!--
-->**: **read item**
**[Applicable Outlook
mode](https://learn.microsoft.com/office/dev/add-ins/outlook/outlook-add-ins-overview#extension-points)<!--
-->**: Compose or Read
The `restUrl` value can be used to make [REST API](https://learn.microsoft.com/outlook/rest/) calls to the user's
mailbox.
#### Examples
```TypeScript
// Link to full sample:
https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/85-tokens-and-service-calls/basic-rest-cors.yaml
Office.context.mailbox.getCallbackTokenAsync({ isRest: true }, function (result) {
const ewsId = Office.context.mailbox.item.itemId;
const token = result.value;
const restId = Office.context.mailbox.convertToRestId(ewsId, Office.MailboxEnums.RestVersion.v2_0);
const getMessageUrl = Office.context.mailbox.restUrl + '/v2.0/me/messages/' + restId;
const xhr = new XMLHttpRequest();
xhr.open('GET', getMessageUrl);
xhr.setRequestHeader("Authorization", "Bearer " + token);
xhr.onload = function (e) {
console.log(this.response);
}
xhr.send();
});
...
console.log("EWS URL: " + Office.context.mailbox.ewsUrl);
const ewsId = Office.context.mailbox.item.itemId;
console.log("EWS item ID: " + Office.context.mailbox.item.itemId);
console.log("REST URL: " + Office.context.mailbox.restUrl);
const restId = Office.context.mailbox.convertToRestId(ewsId, Office.MailboxEnums.RestVersion.v2_0);
console.log("REST item ID: " + restId);
const ewsId2 = Office.context.mailbox.convertToEwsId(restId, Office.MailboxEnums.RestVersion.v2_0);
console.log("EWS ID (from REST ID): " + ewsId2);
```
isPreview: false
isDeprecated: false
syntax:
content: 'restUrl: string;'
return:
type: string
- name: userProfile
uid: 'outlook!Office.Mailbox#userProfile:member'
package: outlook!
fullName: userProfile
summary: >-
Information about the user associated with the mailbox. This includes their account type, display name, email
address, and time zone.
More information is under [Office.UserProfile](xref:outlook!Office.UserProfile:interface)
remarks: ''
isPreview: false
isDeprecated: false
syntax:
content: 'userProfile: UserProfile;'
return:
type: '<xref uid="outlook!Office.UserProfile:interface" />'
methods:
- name: 'addHandlerAsync(eventType, handler, options, callback)'
uid: 'outlook!Office.Mailbox#addHandlerAsync:member(1)'
package: outlook!
fullName: 'addHandlerAsync(eventType, handler, options, callback)'
summary: >-
Adds an event handler for a supported event. **Note**: Events are only available with task pane
implementation.
For supported events, refer to the Mailbox object model [events
section](https://learn.microsoft.com/javascript/api/requirement-sets/outlook/requirement-set-1.7/office.context.mailbox#events)<!--
-->.
remarks: >-
\[ [API set: Mailbox 1.5](/javascript/api/requirement-sets/outlook/outlook-api-requirement-sets) \]
**[Minimum permission
level](https://learn.microsoft.com/office/dev/add-ins/outlook/understanding-outlook-add-in-permissions)<!--
-->**: **read item**
**[Applicable Outlook
mode](https://learn.microsoft.com/office/dev/add-ins/outlook/outlook-add-ins-overview#extension-points)<!--
-->**: Compose or Read
#### Examples
```TypeScript
Office.initialize = function (reason) {
$(document).ready(function () {
Office.context.mailbox.addHandlerAsync(
Office.EventType.ItemChanged,
loadNewItem,
function (result) {
if (result.status === Office.AsyncResultStatus.Failed) {
// Handle error.
}
});
});
};
function loadNewItem(eventArgs) {
const item = Office.context.mailbox.item;
// Check that item is not null.
if (item !== null) {
// Work with item, e.g., define and call function that
// loads the properties of the newly selected item.
loadProps(item);
}
}
```
isPreview: false
isDeprecated: false
syntax:
content: >-
addHandlerAsync(eventType: Office.EventType | string, handler: any, options: Office.AsyncContextOptions,
callback?: (asyncResult: Office.AsyncResult<void>) => void): void;
parameters:
- id: eventType
description: The event that should invoke the handler.
type: '<xref uid="office!Office.EventType:enum" /> | string'
- id: handler
description: >-
The function to handle the event. The function must accept a single parameter, which is an object literal.
The `type` property on the parameter will match the `eventType` parameter passed to `addHandlerAsync`<!--
-->.
type: any
- id: options
description: 'Provides an option for preserving context data of any type, unchanged, for use in a callback.'
type: '<xref uid="office!Office.AsyncContextOptions:interface" />'
- id: callback
description: >-
Optional. When the method completes, the function passed in the `callback` parameter is called with a single
parameter of type `Office.AsyncResult`<!-- -->.
type: '(asyncResult: <xref uid="office!Office.AsyncResult:interface" /><void>) => void'
return:
type: void
description: ''
- name: 'addHandlerAsync(eventType, handler, callback)'
uid: 'outlook!Office.Mailbox#addHandlerAsync:member(2)'
package: outlook!
fullName: 'addHandlerAsync(eventType, handler, callback)'
summary: >-
Adds an event handler for a supported event. **Note**: Events are only available with task pane
implementation.
For supported events, refer to the Mailbox object model [events
section](https://learn.microsoft.com/javascript/api/requirement-sets/outlook/requirement-set-1.7/office.context.mailbox#events)<!--
-->.
remarks: >-
\[ [API set: Mailbox 1.5](/javascript/api/requirement-sets/outlook/outlook-api-requirement-sets) \]
**[Minimum permission
level](https://learn.microsoft.com/office/dev/add-ins/outlook/understanding-outlook-add-in-permissions)<!--
-->**: **read item**
**[Applicable Outlook
mode](https://learn.microsoft.com/office/dev/add-ins/outlook/outlook-add-ins-overview#extension-points)<!--
-->**: Compose or Read
isPreview: false
isDeprecated: false
syntax:
content: >-
addHandlerAsync(eventType: Office.EventType | string, handler: any, callback?: (asyncResult:
Office.AsyncResult<void>) => void): void;
parameters:
- id: eventType
description: The event that should invoke the handler.
type: '<xref uid="office!Office.EventType:enum" /> | string'
- id: handler
description: >-
The function to handle the event. The function must accept a single parameter, which is an object literal.
The `type` property on the parameter will match the `eventType` parameter passed to `addHandlerAsync`<!--
-->.
type: any
- id: callback
description: >-
Optional. When the method completes, the function passed in the `callback` parameter is called with a single
parameter of type `Office.AsyncResult`<!-- -->.
type: '(asyncResult: <xref uid="office!Office.AsyncResult:interface" /><void>) => void'
return:
type: void
description: ''
- name: 'convertToEwsId(id, restVersion)'
uid: 'outlook!Office.Mailbox#convertToEwsId:member(1)'
package: outlook!
fullName: 'convertToEwsId(id, restVersion)'
summary: Converts a supported ID into the Exchange Web Services (EWS) format.
remarks: >-
\[ [API set: Mailbox 1.3](/javascript/api/requirement-sets/outlook/outlook-api-requirement-sets) \]
**[Minimum permission
level](https://learn.microsoft.com/office/dev/add-ins/outlook/understanding-outlook-add-in-permissions)<!--
-->**: **restricted**
**[Applicable Outlook
mode](https://learn.microsoft.com/office/dev/add-ins/outlook/outlook-add-ins-overview#extension-points)<!--
-->**: Compose or Read
**Important**:
- This method isn't supported in Outlook on Android or on iOS. For more information on supported APIs in Outlook
mobile, see [Outlook JavaScript APIs supported in Outlook on mobile
devices](https://learn.microsoft.com/office/dev/add-ins/outlook/outlook-mobile-apis)<!-- -->.
- Item IDs retrieved via a REST API (such as the Outlook Mail API or the Microsoft Graph) use a different format
than the format used by EWS. The `convertToEwsId` method converts a REST-formatted ID into the proper format for
EWS.
#### Examples
```TypeScript
// Link to full sample:
https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/85-tokens-and-service-calls/ids-and-urls.yaml
console.log("EWS URL: " + Office.context.mailbox.ewsUrl);
const ewsId = Office.context.mailbox.item.itemId;
console.log("EWS item ID: " + Office.context.mailbox.item.itemId);
console.log("REST URL: " + Office.context.mailbox.restUrl);
const restId = Office.context.mailbox.convertToRestId(ewsId, Office.MailboxEnums.RestVersion.v2_0);
console.log("REST item ID: " + restId);
const ewsId2 = Office.context.mailbox.convertToEwsId(restId, Office.MailboxEnums.RestVersion.v2_0);
console.log("EWS ID (from REST ID): " + ewsId2);
```
isPreview: false
isDeprecated: false
syntax:
content: 'convertToEwsId(id: string, restVersion: MailboxEnums.RestVersion | string): string;'
parameters:
- id: id
description: >-
The ID to be converted into EWS format. This string can be an item ID formatted for the Outlook REST APIs or
a conversation ID retrieved from `Office.context.mailbox.item.conversationId`<!-- -->.
type: string
- id: restVersion
description: A value indicating the version of the Outlook REST API used to retrieve the item ID.
type: '<xref uid="outlook!Office.MailboxEnums.RestVersion:enum" /> | string'
return:
type: string
description: ''
- name: convertToLocalClientTime(timeValue)
uid: 'outlook!Office.Mailbox#convertToLocalClientTime:member(1)'
package: outlook!
fullName: convertToLocalClientTime(timeValue)
summary: >-
Gets a dictionary containing time information in local client time.
The dates and times used by a mail app for Outlook on the web or on desktop clients can use different time zones.
Outlook uses the client computer time zone; Outlook on the web uses the time zone set on the Exchange Admin Center
(EAC). You should handle date and time values so that the values you display on the user interface are always
consistent with the time zone that the user expects.
If the mail app is running in Outlook on desktop clients, the `convertToLocalClientTime` method will return a
dictionary object with the values set to the client computer time zone. If the mail app is running in Outlook on
the web, the `convertToLocalClientTime` method will return a dictionary object with the values set to the time
zone specified in the EAC.
remarks: >-
**[Minimum permission
level](https://learn.microsoft.com/office/dev/add-ins/outlook/understanding-outlook-add-in-permissions)<!--
-->**: **read item**
**[Applicable Outlook
mode](https://learn.microsoft.com/office/dev/add-ins/outlook/outlook-add-ins-overview#extension-points)<!--
-->**: Compose or Read
isPreview: false
isDeprecated: false
syntax:
content: 'convertToLocalClientTime(timeValue: Date): LocalClientTime;'
parameters:
- id: timeValue
description: A `Date` object.
type: Date
return:
type: '<xref uid="outlook!Office.LocalClientTime:interface" />'
description: ''
- name: 'convertToRestId(id, restVersion)'
uid: 'outlook!Office.Mailbox#convertToRestId:member(1)'
package: outlook!
fullName: 'convertToRestId(id, restVersion)'
summary: Converts a supported ID into REST format.
remarks: >-
\[ [API set: Mailbox 1.3](/javascript/api/requirement-sets/outlook/outlook-api-requirement-sets) \]
**[Minimum permission
level](https://learn.microsoft.com/office/dev/add-ins/outlook/understanding-outlook-add-in-permissions)<!--
-->**: **restricted**
**[Applicable Outlook
mode](https://learn.microsoft.com/office/dev/add-ins/outlook/outlook-add-ins-overview#extension-points)<!--
-->**: Compose or Read
**Important**:
- This method isn't supported in Outlook on Android or on iOS. For more information on supported APIs in Outlook
mobile, see [Outlook JavaScript APIs supported in Outlook on mobile
devices](https://learn.microsoft.com/office/dev/add-ins/outlook/outlook-mobile-apis)<!-- -->.
- Item IDs retrieved via Exchange Web Services (EWS) or via the `itemId` property use a different format than the
format used by REST APIs (such as the [Outlook Mail
API](https://learn.microsoft.com/previous-versions/office/office-365-api/api/version-2.0/mail-rest-operations) or
the [Microsoft Graph](https://graph.microsoft.io/)<!-- -->). The `convertToRestId` method converts an
EWS-formatted ID into the proper format for REST.
#### Examples
```TypeScript
// Link to full sample:
https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/85-tokens-and-service-calls/basic-rest-cors.yaml
Office.context.mailbox.getCallbackTokenAsync({ isRest: true }, function (result) {
const ewsId = Office.context.mailbox.item.itemId;
const token = result.value;
const restId = Office.context.mailbox.convertToRestId(ewsId, Office.MailboxEnums.RestVersion.v2_0);
const getMessageUrl = Office.context.mailbox.restUrl + '/v2.0/me/messages/' + restId;
const xhr = new XMLHttpRequest();
xhr.open('GET', getMessageUrl);
xhr.setRequestHeader("Authorization", "Bearer " + token);
xhr.onload = function (e) {
console.log(this.response);
}
xhr.send();
});
...
console.log("EWS URL: " + Office.context.mailbox.ewsUrl);
const ewsId = Office.context.mailbox.item.itemId;
console.log("EWS item ID: " + Office.context.mailbox.item.itemId);
console.log("REST URL: " + Office.context.mailbox.restUrl);
const restId = Office.context.mailbox.convertToRestId(ewsId, Office.MailboxEnums.RestVersion.v2_0);
console.log("REST item ID: " + restId);
const ewsId2 = Office.context.mailbox.convertToEwsId(restId, Office.MailboxEnums.RestVersion.v2_0);
console.log("EWS ID (from REST ID): " + ewsId2);
```
isPreview: false
isDeprecated: false
syntax:
content: 'convertToRestId(id: string, restVersion: MailboxEnums.RestVersion | string): string;'
parameters:
- id: id
description: >-
The ID to be converted into REST format. This string can be an item ID formatted for EWS that's usually
retrieved from `Office.context.mailbox.item.itemId`<!-- -->, a conversation ID retrieved from
`Office.context.mailbox.item.conversationId`<!-- -->, or a series ID retrieved from
`Office.context.mailbox.item.seriesId`<!-- -->.
type: string
- id: restVersion
description: A value indicating the version of the Outlook REST API used with the converted ID.
type: '<xref uid="outlook!Office.MailboxEnums.RestVersion:enum" /> | string'
return:
type: string
description: ''
- name: convertToUtcClientTime(input)
uid: 'outlook!Office.Mailbox#convertToUtcClientTime:member(1)'
package: outlook!
fullName: convertToUtcClientTime(input)
summary: >-
Gets a `Date` object from a dictionary containing time information.
The `convertToUtcClientTime` method converts a dictionary containing a local date and time to a `Date` object with
the correct values for the local date and time.
remarks: >-
**[Minimum permission
level](https://learn.microsoft.com/office/dev/add-ins/outlook/understanding-outlook-add-in-permissions)<!--
-->**: **read item**
**[Applicable Outlook
mode](https://learn.microsoft.com/office/dev/add-ins/outlook/outlook-add-ins-overview#extension-points)<!--
-->**: Compose or Read
#### Examples
```TypeScript
// Represents 3:37 PM PDT on Monday, August 26, 2019.
const input = {
date: 26,
hours: 15,
milliseconds: 2,
minutes: 37,
month: 7,
seconds: 2,
timezoneOffset: -420,
year: 2019
};
// result should be a Date object.
const result = Office.context.mailbox.convertToUtcClientTime(input);
// Output should be "2019-08-26T22:37:02.002Z".
console.log(result.toISOString());
```
isPreview: false
isDeprecated: false
syntax:
content: 'convertToUtcClientTime(input: LocalClientTime): Date;'
parameters:
- id: input
description: The local time value to convert.
type: '<xref uid="outlook!Office.LocalClientTime:interface" />'
return:
type: Date
description: A Date object with the time expressed in UTC.
- name: displayAppointmentForm(itemId)
uid: 'outlook!Office.Mailbox#displayAppointmentForm:member(1)'
package: outlook!
fullName: displayAppointmentForm(itemId)
summary: >-
Displays an existing calendar appointment.
The `displayAppointmentForm` method opens an existing calendar appointment in a new window on the desktop.
In Outlook on Mac, you can use this method to display a single appointment that isn't part of a recurring series,
or the master appointment of a recurring series. However, you can't display an instance of the series because you
can't access the properties (including the item ID) of instances of a recurring series.
In Outlook on the web, this method opens the specified form only if the body of the form is less than or equal to
32K characters.
If the specified item identifier does not identify an existing appointment, a blank pane opens on the client
computer or device, and no error message is returned.
remarks: >-
\[ [API set: Mailbox 1.1](/javascript/api/requirement-sets/outlook/outlook-api-requirement-sets) \]
**[Minimum permission
level](https://learn.microsoft.com/office/dev/add-ins/outlook/understanding-outlook-add-in-permissions)<!--
-->**: **read item**
**[Applicable Outlook
mode](https://learn.microsoft.com/office/dev/add-ins/outlook/outlook-add-ins-overview#extension-points)<!--
-->**: Compose or Read
**Important**: This method isn't supported in Outlook on Android or on iOS. For more information on supported
APIs in Outlook mobile, see [Outlook JavaScript APIs supported in Outlook on mobile
devices](https://learn.microsoft.com/office/dev/add-ins/outlook/outlook-mobile-apis)<!-- -->.
#### Examples
```TypeScript
// Link to full sample:
https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/55-display-items/display-existing-appointment.yaml
const itemId = $("#itemId").val();
Office.context.mailbox.displayAppointmentForm(itemId);
```
isPreview: false
isDeprecated: false
syntax:
content: 'displayAppointmentForm(itemId: string): void;'
parameters:
- id: itemId
description: The Exchange Web Services (EWS) identifier for an existing calendar appointment.
type: string
return:
type: void
description: ''
- name: displayMessageForm(itemId)
uid: 'outlook!Office.Mailbox#displayMessageForm:member(1)'
package: outlook!
fullName: displayMessageForm(itemId)
summary: >-
Displays an existing message.
The `displayMessageForm` method opens an existing message in a new window on the desktop.
In Outlook on the web, this method opens the specified form only if the body of the form is less than or equal to
32K characters.
If the specified item identifier doesn't identify an existing message, no message will be displayed on the client
computer, and no error message is returned.
remarks: >-
\[ [API set: Mailbox 1.1](/javascript/api/requirement-sets/outlook/outlook-api-requirement-sets) \]
**[Minimum permission
level](https://learn.microsoft.com/office/dev/add-ins/outlook/understanding-outlook-add-in-permissions)<!--
-->**: **read item**
**[Applicable Outlook
mode](https://learn.microsoft.com/office/dev/add-ins/outlook/outlook-add-ins-overview#extension-points)<!--
-->**: Compose or Read
**Important**:
- This method isn't supported in Outlook on Android or on iOS. For more information on supported APIs in Outlook
mobile, see [Outlook JavaScript APIs supported in Outlook on mobile
devices](https://learn.microsoft.com/office/dev/add-ins/outlook/outlook-mobile-apis)<!-- -->.
- Don't use the `displayMessageForm` with an itemId that represents an appointment. Use the
`displayAppointmentForm` method to display an existing appointment, and `displayNewAppointmentForm` to display a
form to create a new appointment.
#### Examples
```TypeScript
// Link to full sample:
https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/55-display-items/display-existing-message.yaml
const itemId = $("#itemId").val();
Office.context.mailbox.displayMessageForm(itemId);
```
isPreview: false
isDeprecated: false
syntax:
content: 'displayMessageForm(itemId: string): void;'
parameters:
- id: itemId
description: The Exchange Web Services (EWS) identifier for an existing message.
type: string
return:
type: void
description: ''
- name: displayNewAppointmentForm(parameters)
uid: 'outlook!Office.Mailbox#displayNewAppointmentForm:member(1)'
package: outlook!
fullName: displayNewAppointmentForm(parameters)
summary: >-
Displays a form for creating a new calendar appointment.
The `displayNewAppointmentForm` method opens a form that enables the user to create a new appointment or meeting.
If parameters are specified, the appointment form fields are automatically populated with the contents of the
parameters.
In Outlook on the web, this method always displays a form with an attendees field. If you don't specify any
attendees as input arguments, the method displays a form with a **Save** button. If you have specified
attendees, the form would include the attendees and a **Send** button.
In the Outlook rich client and Outlook RT, if you specify any attendees or resources in the
`requiredAttendees`<!-- -->, `optionalAttendees`<!-- -->, or `resources` parameter, this method displays a meeting
form with a **Send** button. If you don't specify any recipients, this method displays an appointment form
with a **Save & Close** button.
If any of the parameters exceed the specified size limits, or if an unknown parameter name is specified, an
exception is thrown.
remarks: >-
\[ [API set: Mailbox 1.1](/javascript/api/requirement-sets/outlook/outlook-api-requirement-sets) \]
**[Minimum permission
level](https://learn.microsoft.com/office/dev/add-ins/outlook/understanding-outlook-add-in-permissions)<!--
-->**: **read item**
**[Applicable Outlook
mode](https://learn.microsoft.com/office/dev/add-ins/outlook/outlook-add-ins-overview#extension-points)<!--
-->**: Read
**Important**: This method isn't supported in Outlook on Android or on iOS. For more information on supported
APIs in Outlook mobile, see [Outlook JavaScript APIs supported in Outlook on mobile
devices](https://learn.microsoft.com/office/dev/add-ins/outlook/outlook-mobile-apis)<!-- -->.
#### Examples
```TypeScript
// Link to full sample:
https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/55-display-items/display-new-appointment.yaml
const start = new Date();
const end = new Date();
end.setHours(start.getHours() + 1);
Office.context.mailbox.displayNewAppointmentForm({
requiredAttendees: ["bob@contoso.com"],
optionalAttendees: ["sam@contoso.com"],
start: start,
end: end,
location: "Home",
subject: "meeting",
resources: ["projector@contoso.com"],
body: "Hello World!"
});
```
isPreview: false
isDeprecated: false
syntax:
content: 'displayNewAppointmentForm(parameters: AppointmentForm): void;'
parameters:
- id: parameters
description: An `AppointmentForm` describing the new appointment. All properties are optional.
type: '<xref uid="outlook!Office.AppointmentForm:interface" />'
return:
type: void
description: ''
- name: displayNewMessageForm(parameters)
uid: 'outlook!Office.Mailbox#displayNewMessageForm:member(1)'
package: outlook!
fullName: displayNewMessageForm(parameters)
summary: >-
Displays a form for creating a new message.
The `displayNewMessageForm` method opens a form that enables the user to create a new message. If parameters are
specified, the message form fields are automatically populated with the contents of the parameters.
If any of the parameters exceed the specified size limits, or if an unknown parameter name is specified, an
exception is thrown.
remarks: >-
\[ [API set: Mailbox 1.6](/javascript/api/requirement-sets/outlook/outlook-api-requirement-sets) \]
**[Minimum permission
level](https://learn.microsoft.com/office/dev/add-ins/outlook/understanding-outlook-add-in-permissions)<!--
-->**: **read item**
**[Applicable Outlook
mode](https://learn.microsoft.com/office/dev/add-ins/outlook/outlook-add-ins-overview#extension-points)<!--
-->**: Read
#### Examples
```TypeScript
// Link to full sample:
https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/55-display-items/display-new-message.yaml
Office.context.mailbox.displayNewMessageForm({
toRecipients: Office.context.mailbox.item.to, // Copies the To line from current item
ccRecipients: ["sam@contoso.com"],
subject: "Outlook add-ins are cool!",