From c8512bcf599912b1e1a41e363eacf0785233481f Mon Sep 17 00:00:00 2001 From: mouna-elmaazouzi Date: Wed, 19 Apr 2023 12:58:43 +0000 Subject: [PATCH 01/13] OAuth2 connection update --- README.md | 50 +++++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 47 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index b0327b0..a50da8a 100644 --- a/README.md +++ b/README.md @@ -71,22 +71,66 @@ The available properties of `paramObj` are: |Parameter|Type|Description|Can be Null or undefined| |---------|--- |------|------| -| name | text | Name of the provider. Currently, the only provider available is "Microsoft". |No +| name | text | Name of the provider. Available values: "Microsoft", "Google" or "" (if "" or undefined/null attribute, the authenticateURI and the tokenURI need to be filled by the 4D developer).|Yes | permission | text | |No | clientId | text | The client ID assigned to the app by the registration portal.|No | redirectURI | text | (Not used in service mode) The redirect_uri of your app, the location where the authorization server sends the user once the app has been successfully authorized. When you call the `.getToken()` class function, a web server included in 4D NetKit is started on the port specified in this parameter to intercept the provider's authorization response.|No in signedIn mode, Yes in service mode -| scope | text or collection | Text: A space-separated list of the Microsoft Graph permissions that you want the user to consent to.
Collection: Collection of Microsoft Graph permissions. |No +| scope | text or collection | Text: A space-separated list of the Microsoft Graph permissions that you want the user to consent to.
Collection: Collection of Microsoft Graph permissions. |Yes | tenant | text | The {tenant} value in the path of the request can be used to control who can sign into the application. The allowed values are: Default is "common". |Yes | authenticateURI | text | Uri used to do the Authorization request. By default: "https://login.microsoftonline.com/{tenant}/oauth2/v2.0/authorize". |Yes | tokenURI | text | Uri used to request an access token. By default: "https://login.microsoftonline.com/{tenant}/oauth2/v2.0/token". |Yes | clientSecret | text | The application secret that you created for your app in the app registration portal. Required for web apps. |Yes | token | object | If this property exists, the `getToken()` function uses this token object to calculate which request must be sent. It is automatically updated with the token received by the `getToken()` function. |Yes | timeout|real| Waiting time in seconds (by default 120s).|Yes +| prompt | text |(Optional) A space-delimited, case-sensitive list of prompts to present the user.

Possible values are:
(if you don't specify this parameter, the user will be prompted only the first time your project requests access. )|Yes| +| loginHint | text | (Optional) This option can be used to inform the Google Authentication Server which user is attempting to authenticate if your application is aware of this information. By prefilling the email field in the sign-in form or by selecting the appropriate multi-login session, the server uses the hint to simplify the login flow either.
Set the parameter value to a sub-identifier or email address that corresponds to the user's Google ID. |Yes| +| accessType | text | (Recommended) Indicates whether your application can refresh access tokens when the user is not present at the browser.
Valid parameter values are online (default) and offline.
Set the value to offline if your application needs to update access tokens when the user is not present at the browser. This is how access tokens are refreshed. This value instructs the Google authorization server to retu"rn a refresh token and an access token the first time that your application exchanges an authorization code for tokens. |Yes| +| clientEmail | text | (mandatory, Google / service mode only) email address of the service account used |No| +| privateKey | text | (Google / service mode only) Private key given by Google. Mandatory if .permission="service" and .name="Google" |No| +| authenticationPage|text or file object|Path of the web page to display in the webbrowser when the authentication code is received correctly in signed in mode (If not present the default page is used).|Yes +| authenticationErrorPage |text or file object| Path of the web page to display in the webbrowser when the authentication server returns an error in signed in mode (If not present the default page is used).|Yes + +:::note + +The authenticationPage and authenticationErrorPage and all the resources associated must be in the same folder. + +::: #### Returned object The returned object's properties correspond to those of the `paramObj` object passed as a parameter. +#### Example (Gmail configuration) + +If the attribute name is equal to "Google": +* the authenticateURI attribute must be filled with the value : "https://accounts.google.com/o/oauth2/auth" +* the tokenURI attribute must be be filled with the value : "https://accounts.google.com/o/oauth2/token" + +```4d + +var $File1; $File2 : 4D.File +var $oAuth2 : cs.NetKit.OAuth2Provider + + +$File1:=Folder("/RESOURCES/").file("OK.html") +$File2:=Folder("/RESOURCES/").file("KO.html") + +$param.name:="Google" +$param.permission:="signedIn" +$param.clientId:="" +$param.clientSecret:="" +$param.redirectURI:="http://127.0.0.1:50993/authorize/" +$param.scope:="https://www.googleapis.com/auth/gmail.send" +$param.authenticationPage:=$File1 +$param.authenticationErrorPage:=$File2 +// Create new OAuth2 object +$oAuth2:=cs.NetKit.OAuth2Provider.new($param) +// Ask for a token +$token:=$oAuth2.getToken() +TRACE + +``` + ### OAuth2ProviderObject.getToken() **OAuth2ProviderObject.getToken()** : Object @@ -1213,4 +1257,4 @@ $statusSend:=$smtp.send($email) 2. Execute the method. Your browser opens a page that allows you to authenticate. -3. Log in to your Microsoft Outlook account and check that you've received the email. +3. Log in to your Microsoft Outlook account and check that you've received the email. \ No newline at end of file From 03e32f866423cc16c8049b4793dcbd70a4597c5f Mon Sep 17 00:00:00 2001 From: mouna-elmaazouzi Date: Wed, 19 Apr 2023 13:20:22 +0000 Subject: [PATCH 02/13] small update --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index a50da8a..7181fc9 100644 --- a/README.md +++ b/README.md @@ -117,8 +117,8 @@ $File2:=Folder("/RESOURCES/").file("KO.html") $param.name:="Google" $param.permission:="signedIn" -$param.clientId:="" -$param.clientSecret:="" +$param.clientId:="xxxx" +$param.clientSecret:="xxxx" $param.redirectURI:="http://127.0.0.1:50993/authorize/" $param.scope:="https://www.googleapis.com/auth/gmail.send" $param.authenticationPage:=$File1 From daec4b3b6a63abbc46ed33e6bd1f1033e15af800 Mon Sep 17 00:00:00 2001 From: mouna-elmaazouzi Date: Wed, 19 Apr 2023 13:26:24 +0000 Subject: [PATCH 03/13] Update README.md --- README.md | 6 +----- 1 file changed, 1 insertion(+), 5 deletions(-) diff --git a/README.md b/README.md index 7181fc9..7aa329a 100644 --- a/README.md +++ b/README.md @@ -90,11 +90,7 @@ The available properties of `paramObj` are: | authenticationPage|text or file object|Path of the web page to display in the webbrowser when the authentication code is received correctly in signed in mode (If not present the default page is used).|Yes | authenticationErrorPage |text or file object| Path of the web page to display in the webbrowser when the authentication server returns an error in signed in mode (If not present the default page is used).|Yes -:::note - -The authenticationPage and authenticationErrorPage and all the resources associated must be in the same folder. - -::: +**Note:** The authenticationPage and authenticationErrorPage and all the resources associated must be in the same folder. #### Returned object From 25a09d9eef7a39e893adea41a216274c72d23459 Mon Sep 17 00:00:00 2001 From: mouna-elmaazouzi Date: Thu, 20 Apr 2023 14:40:18 +0000 Subject: [PATCH 04/13] After closure update --- README.md | 30 ++++++++++++++---------------- 1 file changed, 14 insertions(+), 16 deletions(-) diff --git a/README.md b/README.md index 7aa329a..063a65f 100644 --- a/README.md +++ b/README.md @@ -77,18 +77,18 @@ The available properties of `paramObj` are: | redirectURI | text | (Not used in service mode) The redirect_uri of your app, the location where the authorization server sends the user once the app has been successfully authorized. When you call the `.getToken()` class function, a web server included in 4D NetKit is started on the port specified in this parameter to intercept the provider's authorization response.|No in signedIn mode, Yes in service mode | scope | text or collection | Text: A space-separated list of the Microsoft Graph permissions that you want the user to consent to.
Collection: Collection of Microsoft Graph permissions. |Yes | tenant | text | The {tenant} value in the path of the request can be used to control who can sign into the application. The allowed values are:
  • "common" for both Microsoft accounts and work or school accounts
  • "organizations" for work or school accounts only
  • "consumers" for Microsoft accounts only
  • tenant identifiers such as tenant ID or domain name.
Default is "common". |Yes -| authenticateURI | text | Uri used to do the Authorization request. By default: "https://login.microsoftonline.com/{tenant}/oauth2/v2.0/authorize". |Yes -| tokenURI | text | Uri used to request an access token. By default: "https://login.microsoftonline.com/{tenant}/oauth2/v2.0/token". |Yes +| authenticateURI | text | Uri used to do the Authorization request.
Default for Microsoft: "https://login.microsoftonline.com/{tenant}/oauth2/v2.0/authorize".
Default for google: "https://accounts.google.com/o/oauth2/auth". |Yes +| tokenURI | text | Uri used to request an access token.
Default for Microsoft: "https://login.microsoftonline.com/{tenant}/oauth2/v2.0/token".
Default for google: "https://accounts.google.com/o/oauth2/token"|Yes | clientSecret | text | The application secret that you created for your app in the app registration portal. Required for web apps. |Yes | token | object | If this property exists, the `getToken()` function uses this token object to calculate which request must be sent. It is automatically updated with the token received by the `getToken()` function. |Yes | timeout|real| Waiting time in seconds (by default 120s).|Yes -| prompt | text |(Optional) A space-delimited, case-sensitive list of prompts to present the user.

Possible values are:
  • Do not display any authentication or consent screens. Must not be specified with other values.
  • consent :Prompt the user for consent.
  • select_account :Prompt the user to select an account.
(if you don't specify this parameter, the user will be prompted only the first time your project requests access. )|Yes| -| loginHint | text | (Optional) This option can be used to inform the Google Authentication Server which user is attempting to authenticate if your application is aware of this information. By prefilling the email field in the sign-in form or by selecting the appropriate multi-login session, the server uses the hint to simplify the login flow either.
Set the parameter value to a sub-identifier or email address that corresponds to the user's Google ID. |Yes| -| accessType | text | (Recommended) Indicates whether your application can refresh access tokens when the user is not present at the browser.
Valid parameter values are online (default) and offline.
Set the value to offline if your application needs to update access tokens when the user is not present at the browser. This is how access tokens are refreshed. This value instructs the Google authorization server to retu"rn a refresh token and an access token the first time that your application exchanges an authorization code for tokens. |Yes| +| prompt | text |(Optional) A space-delimited, case-sensitive list of prompts to present the user.

Possible values are:
  • none: Do not display any authentication or consent screens. Must not be specified with other values.
  • consent: Prompt the user for consent.
  • select_account: Prompt the user to select an account.
(if you don't specify this parameter, the user will be prompted only the first time your project requests access. )|Yes| +| loginHint | text | (Optional) This option can be used to inform the Google Authentication Server which user is attempting to authenticate if your application is aware of this information. By prefilling the email field in the sign-in form or by selecting the appropriate multi-login session, the server uses the hint to simplify the login flow either.
Set the parameter value to a sub-identifier or email address that corresponds to the user's Google ID. |Yes| +| accessType | text | (Recommended) Indicates whether your application can refresh access tokens when the user is not present at the browser.
Valid parameter values are online (default) and offline.
Set the value to offline if your application needs to update access tokens when the user is not present at the browser. This is how access tokens are refreshed. This value instructs the Google authorization server to return a refresh token and an access token the first time that your application exchanges an authorization code for tokens. |Yes| | clientEmail | text | (mandatory, Google / service mode only) email address of the service account used |No| | privateKey | text | (Google / service mode only) Private key given by Google. Mandatory if .permission="service" and .name="Google" |No| -| authenticationPage|text or file object|Path of the web page to display in the webbrowser when the authentication code is received correctly in signed in mode (If not present the default page is used).|Yes -| authenticationErrorPage |text or file object| Path of the web page to display in the webbrowser when the authentication server returns an error in signed in mode (If not present the default page is used).|Yes +| authenticationPage|text or file object|Path of the web page to display in the web browser when the authentication code is received correctly in signed in mode (If not present the default page is used).|Yes +| authenticationErrorPage |text or file object| Path of the web page to display in the web browser when the authentication server returns an error in signed in mode (If not present the default page is used).|Yes **Note:** The authenticationPage and authenticationErrorPage and all the resources associated must be in the same folder. @@ -96,21 +96,20 @@ The available properties of `paramObj` are: The returned object's properties correspond to those of the `paramObj` object passed as a parameter. -#### Example (Gmail configuration) - -If the attribute name is equal to "Google": -* the authenticateURI attribute must be filled with the value : "https://accounts.google.com/o/oauth2/auth" -* the tokenURI attribute must be be filled with the value : "https://accounts.google.com/o/oauth2/token" +#### Example ```4d +//authentication into google account and token retrieval + var $File1; $File2 : 4D.File var $oAuth2 : cs.NetKit.OAuth2Provider +var $param: Object +$File1:=File("/RESOURCES/OK.html") +$File2:=File("/RESOURCES/KO.html") -$File1:=Folder("/RESOURCES/").file("OK.html") -$File2:=Folder("/RESOURCES/").file("KO.html") - +$param:= New object $param.name:="Google" $param.permission:="signedIn" $param.clientId:="xxxx" @@ -123,7 +122,6 @@ $param.authenticationErrorPage:=$File2 $oAuth2:=cs.NetKit.OAuth2Provider.new($param) // Ask for a token $token:=$oAuth2.getToken() -TRACE ``` From c32494468da92f4fbe18ef6d0f8f8e0308528e89 Mon Sep 17 00:00:00 2001 From: mouna-elmaazouzi Date: Thu, 20 Apr 2023 14:50:22 +0000 Subject: [PATCH 05/13] Update README.md --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 063a65f..981e75d 100644 --- a/README.md +++ b/README.md @@ -78,7 +78,7 @@ The available properties of `paramObj` are: | scope | text or collection | Text: A space-separated list of the Microsoft Graph permissions that you want the user to consent to.
Collection: Collection of Microsoft Graph permissions. |Yes | tenant | text | The {tenant} value in the path of the request can be used to control who can sign into the application. The allowed values are:
  • "common" for both Microsoft accounts and work or school accounts
  • "organizations" for work or school accounts only
  • "consumers" for Microsoft accounts only
  • tenant identifiers such as tenant ID or domain name.
Default is "common". |Yes | authenticateURI | text | Uri used to do the Authorization request.
Default for Microsoft: "https://login.microsoftonline.com/{tenant}/oauth2/v2.0/authorize".
Default for google: "https://accounts.google.com/o/oauth2/auth". |Yes -| tokenURI | text | Uri used to request an access token.
Default for Microsoft: "https://login.microsoftonline.com/{tenant}/oauth2/v2.0/token".
Default for google: "https://accounts.google.com/o/oauth2/token"|Yes +| tokenURI | text | Uri used to request an access token.
Default for Microsoft: "https://login.microsoftonline.com/{tenant}/oauth2/v2.0/token".
Default for google: "https://accounts.google.com/o/oauth2/token".|Yes | clientSecret | text | The application secret that you created for your app in the app registration portal. Required for web apps. |Yes | token | object | If this property exists, the `getToken()` function uses this token object to calculate which request must be sent. It is automatically updated with the token received by the `getToken()` function. |Yes | timeout|real| Waiting time in seconds (by default 120s).|Yes From 2c668fdfd0bfbd021e5430ec33bda0c6f910ff21 Mon Sep 17 00:00:00 2001 From: mouna-elmaazouzi <118451160+mouna-elmaazouzi@users.noreply.github.com> Date: Mon, 9 Oct 2023 16:48:25 +0100 Subject: [PATCH 06/13] Update README.md --- README.md | 49 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 49 insertions(+) diff --git a/README.md b/README.md index 0669545..61858a4 100644 --- a/README.md +++ b/README.md @@ -24,6 +24,7 @@ - [Office365.mail.renameFolder()](#office365mailrenameFolder) - [Office365.mail.reply()](#office365mailreply) - [Office365.mail.send()](#office365mailsend) + - [Office365.mail.update()](#office365mailupdate) - [Well-known folder names](well-known-folder-names) - ["Microsoft" mail object properties](#microsoft-mail-object-properties) - [Status object (Office365 Class)](#status-object) @@ -834,6 +835,54 @@ $status:=$Office365.mail.send($email) The method returns a [status object](#status-object). +### Office365.mail.update() + +**Office365.mail.send**( *mailId* : Text ; *updatedFields* : Object ) : Object + +#### Parameters +|Parameter|Type||Description| +|---------|--- |:---:|------| +|mailId|Text|->|The ID of the email to update| +|updatedFields|Object|<-|email fields to update| +|Result|Object|<-| [Status object](#status-object) | + +#### Description + +`Office365.mail.update()` allows you to update various properties of received or drafted emails. + +In *updatedFields*, you can pass several properties: + +|Property|Type|Description|Updatable only if isDraft = true| +|:----|:----|:----|:----| +|bccRecipients|Recipient|The Bcc recipients for the message.| | +|body|ItemBody|The body of the message.|X| +|categories|String collection|The categories associated with the message.| | +|ccRecipients|Recipient collection|The Cc recipients for the message.| | +|flag|followupFlag|The flag value that indicates the status, start date, due date, or completion date for the message.| | +|from|Recipient|The mailbox owner and sender of the message. Must correspond to the actual mailbox used.|X| +|importance|String|The importance of the message. The possible values are: Low, Normal, High.| | +|inferenceClassification|String|The classification of the message for the user, based on inferred relevance or importance, or on an explicit override. The possible values are: focused or other.| | +|internetMessageId|String|The message ID in the format specified by RFC2822.|X| +|isDeliveryReceiptRequested|Boolean|Indicates whether a read receipt is requested for the message.|X| +|isRead|Boolean|Indicates whether the message has been read.| | +|isReadReceiptRequested|Boolean|Indicates whether a read receipt is requested for the message.|X| +|replyTo|Recipient collection|The email addresses to use when replying.|X| +|sender|Recipient|The account that is actually used to generate the message. Updatable when sending a message from a shared mailbox, or sending a message as a delegate. In any case, the value must correspond to the actual mailbox used.|X| +|subject|String|The subject of the message.|X| +|toRecipients|Recipient collection|The To recipients for the message.| | + +Existing properties that are not included in the updatedFields object will maintain their previous values or be recalculated based on changes to other property values. + +:::note + +Specific properties, such as the body or subject, can only be updated for emails in draft status (isDraft = true). + +::: + +#### Returned object + +The method returns a [status object](#status-object). + ### Well-known folder names From 1e55aa8847bec0a49fc62ade685b81c13ced1ae3 Mon Sep 17 00:00:00 2001 From: mouna-elmaazouzi <118451160+mouna-elmaazouzi@users.noreply.github.com> Date: Tue, 10 Oct 2023 15:34:25 +0100 Subject: [PATCH 07/13] notes updated --- README.md | 17 +++++++---------- 1 file changed, 7 insertions(+), 10 deletions(-) diff --git a/README.md b/README.md index 61858a4..100422e 100644 --- a/README.md +++ b/README.md @@ -837,13 +837,13 @@ The method returns a [status object](#status-object). ### Office365.mail.update() -**Office365.mail.send**( *mailId* : Text ; *updatedFields* : Object ) : Object +**Office365.mail.update**( *mailId* : Text ; *updatedFields* : Object ) : Object #### Parameters |Parameter|Type||Description| |---------|--- |:---:|------| |mailId|Text|->|The ID of the email to update| -|updatedFields|Object|<-|email fields to update| +|updatedFields|Object|->|email fields to update| |Result|Object|<-| [Status object](#status-object) | #### Description @@ -871,13 +871,10 @@ In *updatedFields*, you can pass several properties: |subject|String|The subject of the message.|X| |toRecipients|Recipient collection|The To recipients for the message.| | -Existing properties that are not included in the updatedFields object will maintain their previous values or be recalculated based on changes to other property values. +**Notes:** -:::note - -Specific properties, such as the body or subject, can only be updated for emails in draft status (isDraft = true). - -::: +* Existing properties that are not included in the *updatedFields* object will maintain their previous values or be recalculated based on changes to other property values. +* Specific properties, such as the body or subject, can only be updated for emails in draft status (isDraft = true). #### Returned object @@ -1013,7 +1010,7 @@ $status:=$Office365.mail.send($email) ### Status object -Several Office368.mail functions return a standard `**status object**`, containing the following properties: +Several Office365.mail functions return a standard `**status object**`, containing the following properties: |Property|Type|Description| |---------|--- |------| @@ -1027,7 +1024,7 @@ Basically, you can test the `success` and `statusText` properties of this object ### Error handling -When an error occurs during the execution of an Office368.mail function: +When an error occurs during the execution of an Office365.mail function: - if the function returns a [`**status object**`](#status-object), the error is handled by the status object and no error is thrown, - if the function does not return a **status object**, an error is thrown that you can intercept with a project method installed with `ON ERR CALL`. From a76cf2f65a94ba007bcfb9062efda2857908a930 Mon Sep 17 00:00:00 2001 From: mouna-elmaazouzi <118451160+mouna-elmaazouzi@users.noreply.github.com> Date: Wed, 6 Dec 2023 18:37:20 +0100 Subject: [PATCH 08/13] feature/manage-emails --- README.md | 73 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 73 insertions(+) diff --git a/README.md b/README.md index 100422e..e36e5e4 100644 --- a/README.md +++ b/README.md @@ -37,8 +37,10 @@ - [Google.mail.getLabelList()](#googlemailgetlabellist) - [Google.mail.getMail()](#googlemailgetmail) - [Google.mail.getMailIds()](#googlemailgetmailids) + - [Google.mail.getMails()](#googlemailgetmails) - [Google.mail.send()](#googlemailsend) - [Google.mail.untrash()](#googlemailuntrash) + - [Google.mail.update()](#googlemailupdate) - [Status object (Google Class)](#status-object-google-class) * [Tutorial : Authenticate to the Microsoft Graph API in service mode](#authenticate-to-the-microsoft-graph-api-in-service-mode) @@ -1411,6 +1413,45 @@ https://www.googleapis.com/auth/gmail.readonly https://www.googleapis.com/auth/gmail.metadata ``` +### Google.mail.getMails() + +**Google.mail.getMails**( *mailID* : Collection { ; *options* : Object } ) : Collection + +#### Parameters +|Parameter|Type||Description| +|---------|--- |:---:|------| +|mailID|Collection|->|object collection. Each object contains: id : text : mail id
text collection. Each item contains an id| +|options|Object|->|Options| +|Result|Collection Object | Collection Blob|<-|Collection of emails depending on the *mailType* (JMAP or MIME format)
If no mail is returned, the collection is empty| + + +#### Description + +`Google.mail.getMails()` Gets an emails collection based on the specified mailsIds collection. + +> The maximum supported ids number is 100. In order to get more than 100 mails, it's necessary to call the function multiple times; otherwise, the `Google.mail.getMails()` will return null. + +In *options*, you can pass several properties: + +|Property|Type|Description| +|---------|--- |------| +|format|Text| The format to return the message in. Can be:
  • "minimal": Returns only email message ID and labels; does not return the email headers, body, or payload. Returns a jmap object.
  • "raw": Returns the full email message (default)
  • "metadata": Returns only email message ID, labels, and email headers. Returns a jmap object.
| +|headers|Collection|Collection of strings containing the email headers to be returned. When given and format is "metadata", only include headers specified.| +|mailType|Text|Only available if format is "raw". By default, the same as the *mailType* property of the mail (see [cs.NetKit.Google.new()](#csnetkitgooglenew)). If format="raw", the format can be:
  • "MIME"
  • "JMAP"(Default)
| + + + +#### Returned object + +The method returns a collection of mails in one of the following formats, depending on the `mailType`: + +|Format|Type|Comment| +|---|---|---| +|MIME|Blob|| +|JMAP|Object|Contains an `id` attribute| + + + ### Google.mail.send() **Google.mail.send**( *email* : Text ) : Object
**Google.mail.send**( *email* : Object ) : Object
**Google.mail.send**( *email* : Blob ) : Object @@ -1472,6 +1513,38 @@ https://www.googleapis.com/auth/gmail.modify ``` +### Google.mail.update() + +**Google.mail.update**( *mailID* : Text ; *options* : Object) : Object + +#### Parameters +|Parameter|Type||Description| +|---------|--- |:---:|------| +|mailID|Collection|->|Object collection of the IDs of the messages to modify. Each object contains: id : text : mail id
Text collection. Each item contains an id| +|options|Object|->|Options| +|Result|Object|<-| [Status object](#status-object-google-class) | + +> There is a limit of 1000 IDs per request. + +#### Description + +`Google.mail.update()` adds or removes labels on the specified messages to help categorizing emails. The label can be system labels (e.g., NBOX, SPAM, TRASH, UNREAD, STARRED, IMPORTANT)or custom labels. Multiple labels could be applied simultaneously. + +For more information check out the [label management documentation](https://developers.google.com/gmail/api/guides/labels). + +In *options*, you can pass the following two properties: + +|Property|Type|Description| +|---------|--- |------| +|addLabelIds|Collection|A collection of label IDs to add to messages.| +|removeLabelIds|Collection|A collection of label IDs to remove from messages.| + + +#### Returned object + +The method returns a standard [**status object**](#status-object-google-class). + + ### Status object (Google class) Several Google.mail functions return a `status object`, containing the following properties: From 9681f7b0c30dd1f1199aba96d864f60bd1d1fd83 Mon Sep 17 00:00:00 2001 From: mouna-elmaazouzi <118451160+mouna-elmaazouzi@users.noreply.github.com> Date: Wed, 6 Dec 2023 18:41:06 +0100 Subject: [PATCH 09/13] README.md update --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index e36e5e4..46379ed 100644 --- a/README.md +++ b/README.md @@ -1528,7 +1528,7 @@ https://www.googleapis.com/auth/gmail.modify #### Description -`Google.mail.update()` adds or removes labels on the specified messages to help categorizing emails. The label can be system labels (e.g., NBOX, SPAM, TRASH, UNREAD, STARRED, IMPORTANT)or custom labels. Multiple labels could be applied simultaneously. +`Google.mail.update()` adds or removes labels on the specified messages to help categorizing emails. The label can be system labels (e.g., NBOX, SPAM, TRASH, UNREAD, STARRED, IMPORTANT) or custom labels. Multiple labels could be applied simultaneously. For more information check out the [label management documentation](https://developers.google.com/gmail/api/guides/labels). From 66897f6968fd76a1dc5f2da8d4f1e9d25c787891 Mon Sep 17 00:00:00 2001 From: mouna-elmaazouzi <118451160+mouna-elmaazouzi@users.noreply.github.com> Date: Tue, 12 Dec 2023 12:30:54 +0100 Subject: [PATCH 10/13] afterclosure updates & exampls added --- README.md | 36 ++++++++++++++++++++++++++---------- 1 file changed, 26 insertions(+), 10 deletions(-) diff --git a/README.md b/README.md index 46379ed..8e88090 100644 --- a/README.md +++ b/README.md @@ -1264,7 +1264,7 @@ $google:=cs.NetKit.Google.new($oAuth2;New object("mailType"; "MIME")) |Parameter|Type||Description| |---------|--- |:---:|------| |mailID|Text|->|ID of the mail to delete | -|permanently|Boolean|->|if permanently is true, deletes a message. Otherwise, moves the specified message to the trash | +|permanently|Boolean|->|if permanently is true, deletes a message permanently. Otherwise, moves the specified message to the trash | |Result|Object|<-|[Status object](#status-object-google-class)| @@ -1285,6 +1285,13 @@ https://mail.google.com/ https://www.googleapis.com/auth/gmail.modify ``` +#### Example + +To delete an email permanently: + +```4d +$status:=$google.mail.delete($mailId; True) +``` ### Google.mail.getLabelList() @@ -1415,21 +1422,21 @@ https://www.googleapis.com/auth/gmail.metadata ### Google.mail.getMails() -**Google.mail.getMails**( *mailID* : Collection { ; *options* : Object } ) : Collection +**Google.mail.getMails**( *mailIDs* : Collection { ; *options* : Object } ) : Collection #### Parameters |Parameter|Type||Description| |---------|--- |:---:|------| -|mailID|Collection|->|object collection. Each object contains: id : text : mail id
text collection. Each item contains an id| +|mailIDs|Collection|->|Collection of strings (mail IDs), or a collection of objects (each object contains an ID property)| |options|Object|->|Options| -|Result|Collection Object | Collection Blob|<-|Collection of emails depending on the *mailType* (JMAP or MIME format)
If no mail is returned, the collection is empty| +|Result|Collection|<-|Collection of mails in format depending on *mailType*: JMAP (collection of objects) or MIME (collection of blobs)
If no mail is returned, the collection is empty| #### Description -`Google.mail.getMails()` Gets an emails collection based on the specified mailsIds collection. +`Google.mail.getMails()` gets a collection of emails based on the specified *mailIDs* collection. -> The maximum supported ids number is 100. In order to get more than 100 mails, it's necessary to call the function multiple times; otherwise, the `Google.mail.getMails()` will return null. +> The maximum number of IDs supported is 100. In order to get more than 100 mails, it's necessary to call the function multiple times; otherwise, the `Google.mail.getMails()` function will return null. In *options*, you can pass several properties: @@ -1441,7 +1448,7 @@ In *options*, you can pass several properties: -#### Returned object +#### Returned value The method returns a collection of mails in one of the following formats, depending on the `mailType`: @@ -1515,12 +1522,12 @@ https://www.googleapis.com/auth/gmail.modify ### Google.mail.update() -**Google.mail.update**( *mailID* : Text ; *options* : Object) : Object +**Google.mail.update**( *mailIDs* : Collection ; *options* : Object) : Object #### Parameters |Parameter|Type||Description| |---------|--- |:---:|------| -|mailID|Collection|->|Object collection of the IDs of the messages to modify. Each object contains: id : text : mail id
Text collection. Each item contains an id| +|mailIDs|Collection|->|Collection of strings (mail IDs), or collection of objects (each object contains an ID property)| |options|Object|->|Options| |Result|Object|<-| [Status object](#status-object-google-class) | @@ -1528,7 +1535,7 @@ https://www.googleapis.com/auth/gmail.modify #### Description -`Google.mail.update()` adds or removes labels on the specified messages to help categorizing emails. The label can be system labels (e.g., NBOX, SPAM, TRASH, UNREAD, STARRED, IMPORTANT) or custom labels. Multiple labels could be applied simultaneously. +`Google.mail.update()` adds or removes labels on the specified messages to help categorizing emails. The label can be a system label (e.g., NBOX, SPAM, TRASH, UNREAD, STARRED, IMPORTANT) or a custom label. Multiple labels could be applied simultaneously. For more information check out the [label management documentation](https://developers.google.com/gmail/api/guides/labels). @@ -1545,6 +1552,15 @@ In *options*, you can pass the following two properties: The method returns a standard [**status object**](#status-object-google-class). +#### Example + +To mark a collection of emails as "unread": + +```4d +$result:=$google.mail.update($mailIds; {addLabelIds: ["UNREAD"]}) +``` + + ### Status object (Google class) Several Google.mail functions return a `status object`, containing the following properties: From 7d586867fbbfec7a7f1ebab7eac4fc94dc7cb03f Mon Sep 17 00:00:00 2001 From: mouna-elmaazouzi <118451160+mouna-elmaazouzi@users.noreply.github.com> Date: Tue, 12 Dec 2023 17:30:49 +0100 Subject: [PATCH 11/13] README.md update --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 8e88090..3a9deb2 100644 --- a/README.md +++ b/README.md @@ -1436,7 +1436,7 @@ https://www.googleapis.com/auth/gmail.metadata `Google.mail.getMails()` gets a collection of emails based on the specified *mailIDs* collection. -> The maximum number of IDs supported is 100. In order to get more than 100 mails, it's necessary to call the function multiple times; otherwise, the `Google.mail.getMails()` function will return null. +> The maximum number of IDs supported is 100. In order to get more than 100 mails, it's necessary to call the function multiple times; otherwise, the `Google.mail.getMails()` function returns null and throws an error. In *options*, you can pass several properties: From 2cc2cfd821f80917a93c9a96b332db3ffcfa888f Mon Sep 17 00:00:00 2001 From: mouna-elmaazouzi <118451160+mouna-elmaazouzi@users.noreply.github.com> Date: Wed, 10 Jan 2024 15:44:45 +0100 Subject: [PATCH 12/13] feature/label-management (#3) * README.md Update 1 * README.md minor updates * README.md minor updates pt2 * README.md Update pt2 * README.md Update after-closure --- README.md | 151 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 151 insertions(+) diff --git a/README.md b/README.md index 3a9deb2..5d94a11 100644 --- a/README.md +++ b/README.md @@ -33,7 +33,10 @@ - [Office365.user.list()](#office365userlist) * [Google class](#google) - [cs.NetKit.Google.new()](#csnetkitgooglenew) + - [Google.mail.createLabel()](#googlemailcreatelabel) - [Google.mail.delete()](#googlemaildelete) + - [Google.mail.deleteLabel()](#googlemaildeletelabel) + - [Google.mail.getLabel()](#googlemailgetlabel) - [Google.mail.getLabelList()](#googlemailgetlabellist) - [Google.mail.getMail()](#googlemailgetmail) - [Google.mail.getMailIds()](#googlemailgetmailids) @@ -41,6 +44,8 @@ - [Google.mail.send()](#googlemailsend) - [Google.mail.untrash()](#googlemailuntrash) - [Google.mail.update()](#googlemailupdate) + - [Google.mail.updateLabel()](#googlemailupdatelabel) + - [labelInfo object](#labelinfo-object) - [Status object (Google Class)](#status-object-google-class) * [Tutorial : Authenticate to the Microsoft Graph API in service mode](#authenticate-to-the-microsoft-graph-api-in-service-mode) @@ -1256,6 +1261,40 @@ $oAuth2:=New OAuth2 provider($param) $google:=cs.NetKit.Google.new($oAuth2;New object("mailType"; "MIME")) ``` +### Google.mail.createLabel() + +**Google.mail.createLabel**( *labelInfo* : Object ) : Object + +#### Parameters +|Parameter|Type||Description| +|---------|--- |:---:|------| +|[labelInfo](#labelinfo-object)|Object|->|Label information.| +|Result|Object|<-|[Status object](#status-object-google-class)| + +#### Description + +`Google.mail.createLabel()` creates a new label. + +#### Returned object + +The method returns a [**status object**](status-object-google-class) with an additional "label" property: + +|Property|Type|Description| +|---------|--- |------| +|label|Object|contains a newly created instance of Label (see [labelInfo](#labelinfo-object))| +|success|Boolean| [see Status object](#status-object-google-class)| +|statusText|Text| [see Status object](#status-object-google-class)| +|errors|Collection| [see Status object](#status-object-google-class)| + +#### Example + +To create a label named 'Backup': + +```4d +$status:=$google.mail.createLabel({name: "Backup"}) +$labelId:=$status.label.id +``` + ### Google.mail.delete() **Google.mail.delete**( *mailID* : Text { ; *permanently* : Boolean } ) : Object @@ -1293,6 +1332,71 @@ To delete an email permanently: $status:=$google.mail.delete($mailId; True) ``` +### Google.mail.deleteLabel() + +**Google.mail.deleteLabel**( *labelId* : Text ) : Object + +#### Parameters +|Parameter|Type||Description| +|---------|--- |:---:|------| +|labelId|Text|->|The ID of the label| +|Result|Object|<-|[Status object](#status-object-google-class)| + +#### Description + +`Google.mail.deleteLabel()` immediately and permanently deletes the specified label and removes it from any messages and threads that it is applied to. +> This method is only available for labels with type="user". + +#### Returned object + +The method returns a standard [**status object**](#status-object-google-class). + +#### Example + +To delete a label: + +```4d +$status:=$google.mail.deleteLabel($labelId) + +``` + +### Google.mail.getLabel() + +**Google.mail.getLabel**( *labelId* : Text ) : Object + +#### Parameters +|Parameter|Type||Description| +|---------|--- |:---:|------| +|labelId|Text|->|The ID of the label| +|Result|Object|<-|[labelInfo](#labelinfo-object)| + +#### Description + +`Google.mail.getLabel()` returns the information of a label as a [labelInfo](#labelinfo-object) object. + +#### Returned object + +The returned [**labelInfo**](#labelinfo-object) object contains the following additional properties: + + +|Property|Type|Description| +|---------|---|------| +|messagesTotal|Integer|The total number of messages with the label.| +|messagesUnread|Integer|The number of unread messages with the label.| +|threadsTotal|Integer|The total number of threads with the label.| +|threadsUnread|Integer|The number of unread threads with the label.| + +#### Example + +To retrieve the label name, total message count, and unread messages: + +```4d +$info:=$google.mail.getLabel($labelId) +$name:=$info.name +$emailNumber:=$info.messagesTotal +$unread:=$info.messagesUnread +``` + ### Google.mail.getLabelList() **Google.mail.getLabelList**() : Object @@ -1560,6 +1664,53 @@ To mark a collection of emails as "unread": $result:=$google.mail.update($mailIds; {addLabelIds: ["UNREAD"]}) ``` +### Google.mail.updateLabel() + +**Google.mail.updateLabel**( *labelId* : Text ; *labelInfo* : Object ) : Object + +#### Parameters +|Parameter|Type||Description| +|---------|--- |:---:|------| +|labelId|Text|->|The ID of the label| +|[labelInfo](#labelinfo-object)|Object|->|Label information to update| +|Result|Object|<-|[Status object](#status-object-google-class)| + +#### Description + +`Google.mail.updateLabel()` updates the specified label. +> This method is only available for labels with type="user". + +#### Returned object + +The method returns a [**status object**](status-object-google-class) with an additional "label" property: + +|Property|Type|Description| +|---------|--- |------| +|label|Object|contains an instance of Label (see [labelInfo](#labelinfo-object))| +|success|Boolean| [see Status object](#status-object-google-class)| +|statusText|Text| [see Status object](#status-object-google-class)| +|errors|Collection| [see Status object](#status-object-google-class)| + +#### Example + +To update a previously created label to 'Backup January': + +```4d +$status:=$google.mail.updateLabel($labelId; {name:"Backup January"}) + +``` +### labelInfo object + +Several Google.mail label management methods use a `labelInfo` object, containing the following properties: + +|Property|Type|Description| +|---------|--- |------| +|id|Text|The ID of the label.| +|name|Text|The display name of the label. (mandatory)| +|messageListVisibility|Text|The visibility of messages with this label in the message list.

Can be:
  • "show": Show the label in the message list.
  • "hide": Do not show the label in the message list.
| +|labelListVisibility|Text|The visibility of the label in the label list.

Can be:
  • "labelShow": Show the label in the label list.
  • "labelShowIfUnread" : Show the label if there are any unread messages with that label.
  • "labelHide": Do not show the label in the label list.
| +|[color](https://developers.google.com/gmail/api/reference/rest/v1/users.labels?hl=en#color)|Object|The color to assign to the label (color is only available for labels that have their type set to user).

The color object has 2 attributes :
  • textColor: text: The text color of the label, represented as hex string. This field is required in order to set the color of a label.
  • backgroundColor: text: The background color represented as hex string #RRGGBB (ex for black: #000000). This field is required in order to set the color of a label.
| +|type|Text|The owner type for the label.

Can be:
  • "system": Labels created by Gmail.
  • "user": Custom labels created by the user or application.
System labels are internally created and cannot be added, modified, or deleted. They're may be able to be applied to or removed from messages and threads under some circumstances but this is not guaranteed. For example, users can apply and remove the INBOX and UNREAD labels from messages and threads, but cannot apply or remove the DRAFTS or SENT labels from messages or threads.
User labels are created by the user and can be modified and deleted by the user and can be applied to any message or thread. | ### Status object (Google class) From 7440827f3ea5fdbdd83d706cd6136e11c4a063b9 Mon Sep 17 00:00:00 2001 From: mouna-elmaazouzi <118451160+mouna-elmaazouzi@users.noreply.github.com> Date: Wed, 3 Apr 2024 15:34:02 +0000 Subject: [PATCH 13/13] Google.mail.append() command added --- README.md | 45 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 45 insertions(+) diff --git a/README.md b/README.md index 5434954..3dc95cb 100644 --- a/README.md +++ b/README.md @@ -33,6 +33,7 @@ - [Office365.user.list()](#office365userlist) * [Google class](#google) - [cs.NetKit.Google.new()](#csnetkitgooglenew) + - [Google.mail.append()](#googlemailappend) - [Google.mail.createLabel()](#googlemailcreatelabel) - [Google.mail.delete()](#googlemaildelete) - [Google.mail.deleteLabel()](#googlemaildeletelabel) @@ -1294,6 +1295,50 @@ var $google : cs.NetKit.Google $oAuth2:=New OAuth2 provider($param) $google:=cs.NetKit.Google.new($oAuth2;New object("mailType"; "MIME")) ``` +### Google.mail.append() + +**Google.mail.append**( *mail* : Text { ; *labelIds* : Collection } ) : Object
+**Google.mail.append**( *mail* : Blob { ; *labelIds* : Collection } ) : Object
+**Google.mail.append**( *mail* : Object { ; *labelIds* : Collection } ) : Object
+ +#### Parameters +|Parameter|Type||Description| +|---------|--- |:---:|------| +|mail|Text | Blob | Object|->|Email to be append | +|labelIds|Collection|->|Collection of label IDs to add to messages. By default the DRAFT label is applied| +|Result|Object|<-|[Status object](#status-object-google-class)| + + +#### Description + +`Google.mail.append()` appends *mail* to the user's mailbox as a DRAFT or with designated *labelIds*. + +>If the *labelIds* parameter is passed and the mail has a "from" or "sender" header, the Gmail server automatically adds the SENT label. + +#### Returned object + +The method returns a [**status object**](status-object-google-class) with an additional "id" property: + +|Property|Type|Description| +|---------|--- |------| +|id|Text|id of the email created on the server| +|success|Boolean| [see Status object](#status-object-google-class)| +|statusText|Text| [see Status object](#status-object-google-class)| +|errors|Collection| [see Status object](#status-object-google-class)| + +#### Example + +To append an email : + +```4d +$status:=$google.mail.append($mail) +``` + +By default, the mail is created with a DRAFT label. To change the designated label, pass a second parameter: + +```4d +$status:=$google.mail.append($mail;["INBOX"]) +``` ### Google.mail.createLabel()