New command: m365 outlook message get

[robdy]

Usage

m365 outlook message get [options]

Description

Retrieves specified message

Options

Option	Description
-i, --id <id>	The Id of the message
--userId [userId]	The id of the userfrom which to get the message
--userPrincipalName [userPrincipalName]	The UPN of the user rom which to get the message

Additional Info

If there are other scenarios that require app-only permissions, we can definitely include them in the CLI, but they can only be used with a custom AAD app. We should clarify that in the command's docs.

I think it would be a good idea to add a remark against the option description that passing the user ID or UPN of a shared mailbox user would be accepted.

Above to be added to the docs.

Open points:

Discussed

• [x] As we're using delegated permissions, does it make sense to add --userId parameter? If so, it'd require proper design as it'd potentially be used for different commands. However, it'd require app permissions.
• [x] ADDED I just realized that userId might still be useful when we pull data from shared mailbox. I'll add to the spec later
• [x] DROPPED (reference) - I'm not sure what's the use case for /me/mailFolders/messages endpoint, but I proposed it here anyway to be in line with the endpoint mechanisms. Is it for cases where two emails with the same id are in different folders?
• [x] CHANGED (source) Should we use userId or mailboxId? Effectively, we not always provide a user. It's either a user mailbox or shared mailbox or group mailbox. Seems like mailboxId would be more natural.

[waldekmastykarz]

Thank you for the spec @robdy. Here are a few questions to clarify the spec.

• when is it necessary to use the folderId option?
• we should consider adding a folderName option to allow users pass the name of the folder which we can then look up for them rather than expecting them to look it up manually themselves

As we're using delegated permissions, does it make sense to add --userId parameter? If so, it'd require proper design as it'd potentially be used for different commands. However, it'd require app permissions.

Would it be useful in cases where you want to get a message from another user's inbox that was shared with you? If there are other scenarios that require app-only permissions, we can definitely include them in the CLI, but they can only be used with a custom AAD app. We should clarify that in the command's docs.

[robdy]

Good questions @waldekmastykarz! My comments below:

when is it necessary to use the folderId option?

Honestly, I have no idea. From what I tested, when you provide the message id, Graph checks all the folders anyway. The only case I can see is when two messages with same id are in different folder.

Question - is it even possible in the real life? I checked one possible case - sending messages to yourself. The message in Sent Items has different id than the one in Inbox.

we should consider adding a folderName option to allow users pass the name of the folder which we can then look up for them rather than expecting them to look it up manually themselves

Added to the spec. Do you have an idea how to approach the case when there are two folders with the same name e.g. \2022\ProjectX and 2021\ProjectX?

As we're using delegated permissions, does it make sense to add --userId parameter? If so, it'd require proper design as it'd potentially be used for different commands. However, it'd require app permissions.

Would it be useful in cases where you want to get a message from another user's inbox that was shared with you? If there are other scenarios that require app-only permissions, we can definitely include them in the CLI, but they can only be used with a custom AAD app. We should clarify that in the command's docs.

Perfect, thanks for clarification!

Should we use userId or mailboxId? Effectively, we not always provide a user. It's either a user mailbox or shared mailbox or group mailbox. Seems like mailboxId would be more natural.

This is another question which came to my mind. Added it to the first post. Any thoughts would be appreciated.

[waldekmastykarz]

Question - is it even possible in the real life? I checked one possible case - sending messages to yourself. The message in Sent Items has different id than the one in Inbox.

If it's unclear when the folder is needed, then let's skip it for now and see if anyone raises a valid use case for it.

Added to the spec. Do you have an idea how to approach the case when there are two folders with the same name e.g. \2022\ProjectX and 2021\ProjectX?

Good catch! In that case we should change the option to folderPath and clarify in the docs how it works.

This is another question which came to my mind. Added it to the first post. Any thoughts would be appreciated.

Does the API accept both user ID and mailbox ID or are they the same value?

[robdy]

If it's unclear when the folder is needed, then let's skip it for now and see if anyone raises a valid use case for it.

Removed from spec

Does the API accept both user ID and mailbox ID or are they the same value?

Based on the response from v1.0/users/ these are two different values:

I'll double check it later to be sure

[waldekmastykarz]

@garrytrinder @robdy is there anything else that we should clarify before we proceed with implementation?

[robdy]

@waldekmastykarz there's still this open point:

Should we use userId or mailboxId? Effectively, we do not always provide a user. It's either a user mailbox or shared mailbox or group mailbox. Seems like mailboxId would be more natural.

Another consideration: mailboxId will work with both type of values (id and UserPrincipalName) - should we clarify that in the specification or it's enough to mention that in the command documentation?

[waldekmastykarz]

Just to check if I understand it correctly: you can pass to the API either the user ID or their UPN and that allows us to get the message? If so, then it's great! We only need to find the right name for this option, something like user or userIdentity to communicate that we allow multiple values. Alternatively we can introduce two options userId and userPrincipalName and ask user to specify either one to make it less ambiguous.

[waldekmastykarz]

Hey @robdy, are you still working on this?

[robdy]

@waldekmastykarz yes, I do. I'll do the checking and reply to you later.

[robdy]

Just to check if I understand it correctly: you can pass to the API either the user ID or their UPN and that allows us to get the message?

Yes, that's correct, both options returns the same result:

If so, then it's great! We only need to find the right name for this option, something like user or userIdentity to communicate that we allow multiple values.

What about something starting with mailbox instead of user? For getting emails it's more natural to think about mailboxes, instead of users. For users' mailboxes, these terms are interchangeable. For shared mailboxes you usually don't think about users.

Alternatively we can introduce two options userId and userPrincipalName and ask user to specify either one to make it less ambiguous.

I vote in favor of having one option accepting both id and UPN (better UX in my opinion) but I'm open to suggestions.

[garrytrinder]

I vote in favor of having one option accepting both id and UPN (better UX in my opinion) but I'm open to suggestions.

I agree with having --userId and --userPrincipalName as separate options.

What about something starting with mailbox instead of user? For getting emails it's more natural to think about mailboxes, instead of users. For users' mailboxes, these terms are interchangeable. For shared mailboxes you usually don't think about users.

I'd would say that we stick with the two options above, when a shared mailbox is created in Microsoft 365 it creates a User object in Azure AD, which has an ID and UPN. AFAIK there is no concept of a mailbox ID so may cause confusion as to how to find a Mailbox ID when it's a User ID that is needed. I think it would be a good idea to add a remark against the option description that passing the user ID or UPN of a shared mailbox user would be accepted.

[waldekmastykarz]

@robdy are you still working on this?

[milanholemans]

Opening it back up due to lack of response.

[robdy]

Thanks, Milan and Waldek. I'm happy for someone else to take over. I updated the spec with the current discussion

[milanholemans]

Thanks, Milan and Waldek. I'm happy for someone else to take over. I updated the spec with the current discussion

No problem, thx for updating the spec!

[MathijsVerbeeck]

I would like to work on this one!

[Jwaegebaert]

All yours @MathijsVerbeeck

[milanholemans]

Closing issue because the PR was merged.