From 0086d89173e8fd9020ed1ec19303f895a6546ce0 Mon Sep 17 00:00:00 2001 From: Mathias Vandaele Date: Mon, 16 Sep 2024 16:31:17 +0200 Subject: [PATCH 01/15] doc(email-connector): create a documentation for the new email connector (inbound and outbound) --- .../out-of-the-box-connectors/email.md | 695 ++++++++++++++++++ 1 file changed, 695 insertions(+) create mode 100644 docs/components/connectors/out-of-the-box-connectors/email.md diff --git a/docs/components/connectors/out-of-the-box-connectors/email.md b/docs/components/connectors/out-of-the-box-connectors/email.md new file mode 100644 index 0000000000..7a682095a6 --- /dev/null +++ b/docs/components/connectors/out-of-the-box-connectors/email.md @@ -0,0 +1,695 @@ +--- +id: email +title: Email Connector +sidebar_label: Email Connector +description: The Email Connector allows you to connect your BPMN service with different email protocol. +--- + +import Tabs from "@theme/Tabs"; +import TabItem from "@theme/TabItem"; + + + + + +The **Email Connector** is an outbound Connector that allows you to connect your BPMN service with any email POP3, IMAP +or SMTP server. + +# Prerequisites + +To use the **Email Connector**, you need to have an SMTP, POP3 or IMAP server available. +Use Camunda secrets to avoid exposing your sensitive data as plain text. Follow our documentation +on [managing secrets](/components/console/manage-clusters/manage-secrets.md) to learn more. + +# Authentication + +As of now, there is two different ways to authenticate to a mail server. + +## Simple Authentication + +It allows the user to connect to any SMTP, POP3 or IMAP server using the email address and the associated password. + +# POP3 + +The Post Office Protocol version 3 (POP3) is an Internet standard protocol used by local email clients to retrieve +emails from a remote server over a TCP/IP connection. POP3 allows users to download messages from their email server to +their local computer, where they can be read, managed, or archived even without an internet connection. It operates on a +simple download-and-delete model, meaning emails are typically removed from the server once they are retrieved. + +- `POP3 host`: the host url of the POP3 server. +- `POP3 port`: the host port of the POP3 server. +- `Cryptographic protocol`: It defines how the connection to the server should be secured, TLS, SSL or None. Default is + typically TLS. + +## List Emails + +### Parameters + +This feature allows users to fetch a list of emails from the `INBOX` folder with customizable sorting and limitation +options. + +- `Max Emails to read`: Specify the maximum number of emails to retrieve. This parameter determines the cap on the + number + of emails the task will return. +- `Sort emails by`: Choose the field by which to sort the emails. The currently supported sorting fields are: + - `Sent date`: Sorts emails by the date and time they were sent. + - `Size`: Sorts emails by the size of the email. +- `Sort order`: Define the sort order using either: + - `ASC`: Ascending order, from the oldest or smallest value to the most recent or largest. + - `DESC`: Descending order, from the most recent or largest value to the oldest or smallest. + +### Sorting and Limiting Behavior + +Emails are initially sorted based on the specified sorting field and order. The list is then limited to the number of +emails as defined by the Max Emails to read parameter. For example, if you sort by Sent date in descending order (DESC) +with a limit of one email, the task will return the most recently sent email. + +### Response Structure + +The task returns a list of emails in JSON format. Each email object contains the following information: + +- `messageId`: A unique identifier for the email message. +- `fromAddresses`: An array of email addresses representing the senders. +- `subject`: The subject line of the email. +- `size`: The size of the email in bytes. + +### Example Response + +Example of a returned JSON array: + +```json +[ + { + "messageId":"RandomId", + "fromAddresses":["msa@communication.microsoft.com"], + "subject":"Example", + "size":99865 + }, { + "messageId":"RandomId2", + "fromAddresses":["example@camunda.com"], + "subject":"Example", + "size":48547 + } +] + +``` + +## Read Email + +This functionality retrieves the contents of an email by using the unique `messageId` associated with the email message. + +### Parameters + +- `MessageId`: This is the identifier of the email message you wish to read. It should be provided to locate and return + the specific email. +- `Delete after reading`: This is a boolean parameter. If set to true, the email will be deleted from the server after + it has been read. If false or not set, the email will remain on the server. + +### Response Structure + +Upon successful execution of the task, the response will be a JSON object containing detailed information about the +email: + +- `messageId`: The unique identifier of the email message. +- `fromAddresses`: An array containing the email addresses of the senders. +- `subject`: The subject line of the email. +- `size`: The size of the email in bytes. +- `plainTextBody`: The plain text version of the email body. +- `htmlBody`: The HTML version of the email body, if available. + +### Example Response + +Below is an example of the JSON response returned when a specific email is read: + +```json +{ + "messageId":"MessageId", + "fromAddresses":[ + "example@camunda.com" + ], + "subject":"Example Subject", + "size":99865, + "plainTextBody":"Any text content", + "htmlBody":"Any Html Content" +} +``` + +## Delete Email + +This operation facilitates the removal of an email from the server using the specific `messageId` assigned to the email +message. + +### Parameters + +- `MessageId`: The unique identifier of the email message that needs to be deleted. + +### Response Structure + +After the deletion task is performed, a JSON object is returned to confirm the action: + +- `deleted`: A boolean value that indicates whether the deletion was successful (true) or not (false). +- `messageId`: The identifier of the email message that was attempted to be deleted. + +### Example Response + +The following JSON response exemplifies the result of a successful deletion request: + +```json + +{ + "deleted":true, + "messageId":"MessageId" +} +``` + +## Search Emails + +This feature enables users to perform advanced searches within an email inbox by constructing a criteria-based query +using a JSON object. The search functionality supports complex queries that can combine multiple conditions using +logical operators. + +### Parameters + +A search query is represented as a JSON object. Below is an example of a JSON object that represents a search criteria +using an AND and OR operator to combine multiple conditions: + +```json +{ + "operator":"AND", + "criteria":[ + { + "field":"FROM", + "value":"example@camunda.com" + }, + { + "operator":"OR", + "criteria":[ + { + "field":"SUBJECT", + "value":"urgent" + }, + { + "field":"SUBJECT", + "value":"important" + } + ] + } + ] +} +``` + +The above query will return emails that are from "example@camunda.com" and have a subject containing either "urgent" +or "important". + +A simpler query without logical operators may look like this: + +```json +{ + "field":"FROM", + "value":"example@camunda.com" +} +``` + +The search functionality currently supports the following logical operators: + +- **AND**: Returns emails that match all the specified criteria. +- **OR**: Returns emails that match any of the specified criteria. + +The following email fields can be used to set search criteria: + +- **BODY**: The content of the email body. +- **SUBJECT**: The subject line of the email. +- **FROM**: The email address of the sender. + +When using an operator such as AND or OR, you must also define a criteria array. This array contains the individual +conditions that the search will evaluate against the emails. Each condition within the criteria array is itself a JSON +object with a field and a value. + +#### Notes + +- If an operator is set, the criteria array must also be defined. +- Each criterion within the criteria array is applied to the specified field based on the value associated with it. + +### Example Response + +Returned Response: + +```json +[ + {"messageId":"MessageId", "subject":"Important"}, + {"messageId":"MessageId2", "subject":"Urgent"} +] +``` + +# SMTP + +Simple Mail Transfer Protocol (SMTP) is the standard communication protocol for sending emails across the Internet. It +facilitates mail transfer from a client's email application to the outgoing mail server and between servers for relaying +email messages to their final destination. SMTP operates on a push model, where the sending server pushes the message to +the receiving server for delivery to the appropriate mailbox. + +- `SMTP host`: the host url of the SMTP server. +- `SMTP port`: the host port of the SMTP server. +- `Cryptographic protocol`: It defines how the connection to the server should be secured, TLS, SSL or None. Default is + typically TLS. + +## Send Email + +This task enables users to send an email from the connected email account. + +### Parameters + +- `From`: Specifies the sender's email address(es). This can be a single email address (e.g., 'example@camunda.com'), a + comma-separated list of addresses, or a Friendly Enough Expression Language (FEEL) expression returning a list of + email addresses (e.g., =["example@camunda.com"]). +- `To`: Defines the recipient(s) of the email. Similar to the From parameter, this can be a single email address, a + comma-separated list, or a FEEL expression (e.g., =["example@camunda.com"]). +- `Cc`: (Optional) Indicates the email address(es) to be included in the Carbon Copy field. The format is the same as + the From and TO fields and can include a single address, a list, or a FEEL expression. +- `Bcc`: (Optional) Denotes the email address(es) for Blind Carbon Copy. It follows the same format as the CC field and + ensures that BCC recipients are not visible to other recipients. +- `Subject`: The subject line of the email. +- `Email` Content: The main content of the email. + +### Response Structure + +Upon successfully sending the email, the following JSON response is returned: + +- `subject`: Echoes back the subject of the sent email. +- `sent`: A boolean value indicating the success status of the email being sent (true for success, false for failure). + +### Example Response + +Here's an example of a successful email-sending operation: + +```json +{ + "subject":"Example Subject", + "sent":true +} +``` + +In this response, `sent: true` confirms that the email with the specified subject "Example Subject" has been +successfully dispatched. If the email fails to send, "sent" would be false + +# IMAP + +The Internet Message Access Protocol (IMAP) is a protocol used by email clients to access messages stored on a mail +server, allowing users to view and manage their emails from multiple devices. Unlike POP3, IMAP supports both online and +offline modes, synchronizes email across devices, and allows manipulation of mailboxes (create, delete, and rename) as +well as messages (read, delete, or flag) directly on the server. + +## List Emails + +This feature allows users to fetch a list of emails from a given with customizable sorting and limitation +options. + +### Parameters + +- `Max Emails to read`: Specify the maximum number of emails to retrieve. This parameter determines the cap on the + number + of emails the task will return. +- `Sort emails by`: Choose the field by which to sort the emails. The currently supported sorting fields are: + - `Sent date`: Sorts emails by the date and time they were sent. + - `Size`: Sorts emails by the size of the email. +- `Sort order`: Define the sort order using either: + - `ASC`: Ascending order, from the oldest or smallest value to the most recent or largest. + - `DESC`: Descending order, from the most recent or largest value to the oldest or smallest. +- `Folder`: (Optional) the folder to list emails from, default is `INBOX`. + +### Sorting and Limiting Behavior + +Emails are initially sorted based on the specified sorting field and order. The list is then limited to the number of +emails as defined by the Max Emails to read parameter. For example, if you sort by Sent date in descending order (DESC) +with a limit of one email, the task will return the most recently sent email. + +### Response Structure + +The task returns a list of emails in JSON format. Each email object contains the following information: + +- `messageId`: A unique identifier for the email message. +- `fromAddresses`: An array of email addresses representing the senders. +- `subject`: The subject line of the email. +- `size`: The size of the email in bytes. + +### Example Response + +Example of a returned JSON array: + +```json +[ + { + "messageId":"RandomId", + "fromAddresses":["msa@communication.microsoft.com"], + "subject":"Example", + "size":99865 + }, { + "messageId":"RandomId2", + "fromAddresses":["example@camunda.com"], + "subject":"Example", + "size":48547 + } +] + +``` + +## Read Email + +This task is designed to retrieve an email's details based on the provided `messageId`. + +### Parameters + +- `MessageId`: This parameter requires the unique identifier of the email that needs to be read. +- `Folder`: (Optional) Specifies the folder from which the email should be retrieved. If not provided, the default + folder is `INBOX`. + +### Response Structure + +The task returns a JSON object with detailed information about the email: + +- `messageId`: The unique identifier corresponding to the email message. +- `fromAddresses`: An array containing the email addresses of the sender(s). +- `subject`: The subject line of the email. +- `size`: The size of the email in bytes. +- `plainTextBody`: The plain text version of the email's content. +- `htmlBody`: The HTML version of the email's content, provided it exists. + +### Example Response + +The following JSON structure illustrates the expected response after a successful email retrieval: + +```json +{ + "messageId":"MessageId", + "fromAddresses":[ + "example@camunda.com" + ], + "subject":"Example Subject", + "size":99865, + "plainTextBody":"Any text content", + "htmlBody":"Any Html Content" +} +``` + +## Delete Email + +This task facilitates the deletion of an email from a specified folder using the email's unique `messageId`. + +### Parameters + +- `MessageId`: The identifier of the email message to be deleted. +- `Folder`: (Optional) Specifies the folder from which the email should be deleted. If this parameter is not supplied, + the default folder is assumed to be `INBOX`. + +### Response Structure + +The task provides a JSON object in the response, indicating the outcome of the deletion request: + +- `deleted`: A boolean value that signifies whether the email was successfully deleted (true) or not (false). +- `messageId`: Reiterates the messageId of the email that was targeted for deletion. + +### Example Response + +Here is an example of the JSON response that confirms the successful deletion of an email: + +```json + +{ + "deleted":true, + "messageId":"MessageId" +} +``` + +## Search Emails + +This feature enables users to perform advanced searches within an email inbox by constructing a criteria-based query +using a JSON object. The search functionality supports complex queries that can combine multiple conditions using +logical operators. + +### Parameters + +A search query is represented as a JSON object. Below is an example of a JSON object that represents a search criteria +using an AND and OR operator to combine multiple conditions: + +- `Folder`: (Optional) Specifies the folder from which the email should be deleted. If this parameter is not supplied, + the default folder is assumed to be `INBOX`. +- `Criteria`: _See below_ + +```json +{ + "operator":"AND", + "criteria":[ + { + "field":"FROM", + "value":"example@camunda.com" + }, + { + "operator":"OR", + "criteria":[ + { + "field":"SUBJECT", + "value":"urgent" + }, + { + "field":"SUBJECT", + "value":"important" + } + ] + } + ] +} +``` + +The above query will return emails that are from "example@camunda.com" and have a subject containing either "urgent" +or "important". + +A simpler query without logical operators may look like this: + +```json +{ + "field":"FROM", + "value":"example@camunda.com" +} +``` + +The search functionality currently supports the following logical operators: + +- **AND**: Returns emails that match all the specified criteria. +- **OR**: Returns emails that match any of the specified criteria. + +The following email fields can be used to set search criteria: + +- **BODY**: The content of the email body. +- **SUBJECT**: The subject line of the email. +- **FROM**: The email address of the sender. + +When using an operator such as AND or OR, you must also define a criteria array. This array contains the individual +conditions that the search will evaluate against the emails. Each condition within the criteria array is itself a JSON +object with a field and a value. + +#### Notes + +- If an operator is set, the criteria array must also be defined. +- Each criterion within the criteria array is applied to the specified field based on the value associated with it. + +### Example Response + +Returned Response: + +```json +[ + {"messageId":"MessageId", "subject":"Important"}, + {"messageId":"MessageId2", "subject":"Urgent"} +] +``` + +## Move Email + +This task enables users to transfer an email from one folder to another, streamlining inbox organization. + +### Parameters + +- `MessageId`: The identifier of the email that needs to be moved. +- `Source folder`: (Optional) The folder from which the email will be moved. If not specified, the default is INBOX. +- `Target folder`: The destination folder where the email will be placed. To specify a new folder or a nested hierarchy, + use a dot-separated path (e.g., 'Archive' or 'Projects.2023.January'). The system will automatically create any + non-existing folders in the path. + +### Response Structure + +Upon successful completion of the move operation, the response will contain a JSON object with the following details: + +- `messageId`: The messageId of the email that was moved. +- `from`: The source folder from which the email was moved. +- `to`: The target folder to which the email has been moved. + +### Example Response + +The example below demonstrates the expected JSON response after an email has been successfully moved: + +```json + +{ + "messageId":"VE1P191MB1101730EEA31B2FEAB320143919A2@VE1P191MB1101.EURP191.PROD.OUTLOOK.COM", + "from":"INBOX", + "to":"TEST" +} +``` + + + + + +# Prerequisites + +This inbound connector only work with IMAP server. + +To use the **Email Inbound Connector**, you need to have an IMAP server available. +Use Camunda secrets to avoid exposing your sensitive data as plain text. Follow our documentation +on [managing secrets](/components/console/manage-clusters/manage-secrets.md) to learn more. + +# Authentication + +As of now, there is two different ways to authenticate to a mail server. + +## Simple Authentication + +It allows the user to connect to any IMAP server using the email address and the associated password. + +## Listener information's + +This inbound connector will create a new process each time a new email will be received. + +- `Folder`: (Optional) Specifies the folder that the inbound connector should monitor. The default folder is INBOX. +- `Sync Strategy`: Determines how emails are synchronized when the connector starts: + - `Unseen emails will be sync`: A process instance is created for every unseen email present in the folder at the + time the connector starts. + - `No initial sync. Only new emails`: The connector skips past emails and starts listening for new emails arriving + in the folder. + - `All emails will be sync`: A process instance is created for every email in the folder, regardless of their read + status, when the connector starts. +- `Handling Strategy`: Defines how emails are handled after processing: + - `Mark as read after processing`: Emails that have been processed will be marked as read. + - `Do nothing`: No action will be taken on processed emails. + - `Delete after processing`: Emails that have been processed will be deleted from the folder. + - `Move to another folder after processing`: Processed emails will be moved to another specified folder. + - `Folder`: Indicates the destination folder where emails will be moved after processing. A new folder or folder + hierarchy + can be specified using a dot-separated path (e.g., 'Archive' or 'Projects.2023.January'). Non-existent folders + in the + path will be created automatically. + +### Example Response + +The JSON response below is an example of the data structure produced when an email triggers the creation of a process +instance: + +```json +{ + "messageId":"messageId", + "fromAddresses":["example@camunda.com"], + "subject":"Urgent Test", + "size":65646, + "plainTextBody":"Hey how are you?\r\n", + "htmlBody":"Hello" +} +``` + +This response includes essential email details such as the messageId, sender addresses, subject, size, and the content +of the email both in plain text and HTML format. This information can be used by the process for various workflows, such +as prioritizing tasks, content analysis, and automated responses. + +### Activation condition + +The **Activation condition** is an optional field where you can specify a Friendly Enough Expression Language (FEEL) +expression to control when the Email Inbound Connector should trigger a process instance. This condition acts as a +filter, allowing the process to be initiated only when certain criteria are met by the incoming email. + +#### Example Usage + +For instance, the FEEL expression =(response.subject = "urgent") will ensure that the process is only triggered if the +subject of the incoming email matches "urgent". If this field is left blank, the process will be triggered for every +email received by the connector. + +:::warning By default, the Email Inbound Connector is designed not to execute its handling strategy if it encounters an +email that it cannot process, such as when the activation condition is not fulfilled. ::: + +To ignore messages that do not meet the activation condition and still handle the email, check the **Consume unmatched +events** checkbox. + +| **Consume unmatched events** checkbox | Activation condition | Outcome | +|---------------------------------------|----------------------|--------------------------------------------------------------| +| Checked | Matched | Connector is triggered, handling strategy is applied | +| Unchecked | Matched | Connector is triggered, handling strategy is applied | +| Checked | Unmatched | Connector is not triggered, handling strategy is applied | +| Unchecked | Unmatched | Connector is not triggered, handling strategy is not applied | + +### Correlation + +The **Correlation** section allows you to configure the message correlation parameters. + +:::note +The **Correlation** section is not applicable for the plain **start event** element template of the email Connector. +Plain **start events** are triggered by process instance creation and do not rely on message correlation. +::: + +#### Correlation key + +- **Correlation key (process)** is a FEEL expression that defines the correlation key for the subscription. This + corresponds to the **Correlation key** property of a regular **message intermediate catch event**. +- **Correlation key (payload)** is a FEEL expression used to extract the correlation key from the incoming message. This + expression is evaluated in the Connector Runtime and the result is used to correlate the message. + +For example, given that your correlation key is defined with `myCorrelationKey` process variable, and the incoming email +message contains `value:{correlationKey:myValue}`, your correlation key settings will look like this: + +- **Correlation key (process)**: `=myCorrelationKey` +- **Correlation key (payload)**: `=message.plainTextBody.correlationKey` + +You can also use the key of the message to accomplish this in the **Correlation key (payload)** field with `=key`. + +Learn more about correlation keys in the [messages guide](../../../concepts/messages). + +#### Message ID expression + +The **Message ID expression** is an optional field that allows you to extract the message ID from the incoming message. +The message ID serves as a unique identifier for the message and is used for message correlation. +This expression is evaluated in the Connector Runtime and the result is used to correlate the message. + +In most cases, it is not necessary to configure the **Message ID expression**. However, it is useful if you want to +ensure message deduplication or achieve a certain message correlation behavior. +Learn more about how message IDs influence message correlation in +the [messages guide](../../../concepts/messages#message-correlation-overview). + +For example, if you want to set the message ID to the value of the `messageId` field in the incoming message, you +can configure the **Message ID expression** as follows: + +``` += message.messageId +``` + +#### Message TTL + +The **Message TTL** is an optional field that allows you to set the time-to-live (TTL) for the correlated messages. TTL +defines the time for which the message is buffered in Zeebe before being correlated to the process instance (if it can't +be correlated immediately). +The value is specified as an ISO 8601 duration. For example, `PT1H` sets the TTL to one hour. Learn more about the TTL +concept in Zeebe in the [message correlation guide](../../../concepts/messages#message-buffering). + +### Deduplication + +The **Deduplication** section allows you to configure the Connector deduplication parameters. +Not to be confused with **message deduplication**, **Connector deduplication** is a mechanism in the Connector Runtime +that determines how many emails listener are created if there are multiple occurrences of the **Email Listener +Connector** in the BPMN diagram. + +By default, the Connector runtime deduplicates Connectors based on properties, so elements with the same subscription +properties only result in one subscription. Learn more about deduplication in +the [deduplication guide](../use-connectors/inbound.md#connector-deduplication). + +To customize the deduplication behavior, check the **Manual mode** checkbox and configure the custom deduplication ID. + + + + From 432c58d7cbba8a9f44f23687085cd8050653c5b8 Mon Sep 17 00:00:00 2001 From: Mathias Vandaele Date: Tue, 17 Sep 2024 10:12:29 +0200 Subject: [PATCH 02/15] docs(email-connector): fixes for the side bar --- optimize_sidebars.js | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/optimize_sidebars.js b/optimize_sidebars.js index 37d8adea25..a1ce99eed5 100644 --- a/optimize_sidebars.js +++ b/optimize_sidebars.js @@ -852,7 +852,10 @@ module.exports = { "Automation Anywhere Connector", "components/connectors/out-of-the-box-connectors/automation-anywhere/" ), - + docsLink( + "Email Connector", + "components/connectors/out-of-the-box-connectors/email/" + ), { AWS: [ docsLink( From 89d6e56b23211b216774db8e2c5c57159e292845 Mon Sep 17 00:00:00 2001 From: Mathias Vandaele Date: Tue, 17 Sep 2024 14:32:00 +0200 Subject: [PATCH 03/15] Update docs/components/connectors/out-of-the-box-connectors/email.md Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> --- docs/components/connectors/out-of-the-box-connectors/email.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/components/connectors/out-of-the-box-connectors/email.md b/docs/components/connectors/out-of-the-box-connectors/email.md index 7a682095a6..3262447b04 100644 --- a/docs/components/connectors/out-of-the-box-connectors/email.md +++ b/docs/components/connectors/out-of-the-box-connectors/email.md @@ -53,8 +53,8 @@ options. number of emails the task will return. - `Sort emails by`: Choose the field by which to sort the emails. The currently supported sorting fields are: - - `Sent date`: Sorts emails by the date and time they were sent. - - `Size`: Sorts emails by the size of the email. + - `Sent date`: Sorts emails by the date and time they were sent. + - `Size`: Sorts emails by the size of the email. - `Sort order`: Define the sort order using either: - `ASC`: Ascending order, from the oldest or smallest value to the most recent or largest. - `DESC`: Descending order, from the most recent or largest value to the oldest or smallest. From fc0a212adf237498d6836f967989037c169626cf Mon Sep 17 00:00:00 2001 From: Mathias Vandaele Date: Tue, 17 Sep 2024 14:32:14 +0200 Subject: [PATCH 04/15] Update docs/components/connectors/out-of-the-box-connectors/email.md Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> --- docs/components/connectors/out-of-the-box-connectors/email.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/components/connectors/out-of-the-box-connectors/email.md b/docs/components/connectors/out-of-the-box-connectors/email.md index 3262447b04..f2d300160b 100644 --- a/docs/components/connectors/out-of-the-box-connectors/email.md +++ b/docs/components/connectors/out-of-the-box-connectors/email.md @@ -56,8 +56,8 @@ options. - `Sent date`: Sorts emails by the date and time they were sent. - `Size`: Sorts emails by the size of the email. - `Sort order`: Define the sort order using either: - - `ASC`: Ascending order, from the oldest or smallest value to the most recent or largest. - - `DESC`: Descending order, from the most recent or largest value to the oldest or smallest. + - `ASC`: Ascending order, from the oldest or smallest value to the most recent or largest. + - `DESC`: Descending order, from the most recent or largest value to the oldest or smallest. ### Sorting and Limiting Behavior From 45226cf7c69dd5dc2e6c770cc55dd3545489d503 Mon Sep 17 00:00:00 2001 From: Mathias Vandaele Date: Tue, 17 Sep 2024 14:32:24 +0200 Subject: [PATCH 05/15] Update docs/components/connectors/out-of-the-box-connectors/email.md Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> --- .../out-of-the-box-connectors/email.md | 19 ++++++++++--------- 1 file changed, 10 insertions(+), 9 deletions(-) diff --git a/docs/components/connectors/out-of-the-box-connectors/email.md b/docs/components/connectors/out-of-the-box-connectors/email.md index f2d300160b..4c2c219992 100644 --- a/docs/components/connectors/out-of-the-box-connectors/email.md +++ b/docs/components/connectors/out-of-the-box-connectors/email.md @@ -81,15 +81,16 @@ Example of a returned JSON array: ```json [ { - "messageId":"RandomId", - "fromAddresses":["msa@communication.microsoft.com"], - "subject":"Example", - "size":99865 - }, { - "messageId":"RandomId2", - "fromAddresses":["example@camunda.com"], - "subject":"Example", - "size":48547 + "messageId": "RandomId", + "fromAddresses": ["msa@communication.microsoft.com"], + "subject": "Example", + "size": 99865 + }, + { + "messageId": "RandomId2", + "fromAddresses": ["example@camunda.com"], + "subject": "Example", + "size": 48547 } ] From f2e02adf21ed9e8482c04ba3e3b0aed73ab29931 Mon Sep 17 00:00:00 2001 From: Mathias Vandaele Date: Tue, 17 Sep 2024 14:32:36 +0200 Subject: [PATCH 06/15] Update docs/components/connectors/out-of-the-box-connectors/email.md Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> --- docs/components/connectors/out-of-the-box-connectors/email.md | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/components/connectors/out-of-the-box-connectors/email.md b/docs/components/connectors/out-of-the-box-connectors/email.md index 4c2c219992..c733ca36d6 100644 --- a/docs/components/connectors/out-of-the-box-connectors/email.md +++ b/docs/components/connectors/out-of-the-box-connectors/email.md @@ -93,7 +93,6 @@ Example of a returned JSON array: "size": 48547 } ] - ``` ## Read Email From f3263ba0c1fbf8b71372830a5ddfb7163d108cbc Mon Sep 17 00:00:00 2001 From: Mathias Vandaele Date: Tue, 17 Sep 2024 14:32:46 +0200 Subject: [PATCH 07/15] Update docs/components/connectors/out-of-the-box-connectors/email.md Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> --- .../connectors/out-of-the-box-connectors/email.md | 14 ++++++-------- 1 file changed, 6 insertions(+), 8 deletions(-) diff --git a/docs/components/connectors/out-of-the-box-connectors/email.md b/docs/components/connectors/out-of-the-box-connectors/email.md index c733ca36d6..c6259913a6 100644 --- a/docs/components/connectors/out-of-the-box-connectors/email.md +++ b/docs/components/connectors/out-of-the-box-connectors/email.md @@ -124,14 +124,12 @@ Below is an example of the JSON response returned when a specific email is read: ```json { - "messageId":"MessageId", - "fromAddresses":[ - "example@camunda.com" - ], - "subject":"Example Subject", - "size":99865, - "plainTextBody":"Any text content", - "htmlBody":"Any Html Content" + "messageId": "MessageId", + "fromAddresses": ["example@camunda.com"], + "subject": "Example Subject", + "size": 99865, + "plainTextBody": "Any text content", + "htmlBody": "Any Html Content" } ``` From d28916882f0747b890622c746db8de4705478bab Mon Sep 17 00:00:00 2001 From: Mathias Vandaele Date: Tue, 17 Sep 2024 14:33:07 +0200 Subject: [PATCH 08/15] Update docs/components/connectors/out-of-the-box-connectors/email.md Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> --- docs/components/connectors/out-of-the-box-connectors/email.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/components/connectors/out-of-the-box-connectors/email.md b/docs/components/connectors/out-of-the-box-connectors/email.md index c6259913a6..c106b8b929 100644 --- a/docs/components/connectors/out-of-the-box-connectors/email.md +++ b/docs/components/connectors/out-of-the-box-connectors/email.md @@ -446,8 +446,8 @@ using an AND and OR operator to combine multiple conditions: "operator":"OR", "criteria":[ { - "field":"SUBJECT", - "value":"urgent" + "field": "SUBJECT", + "value": "urgent" }, { "field":"SUBJECT", From 1cde663fc492b410be68f138545d92bf6153feed Mon Sep 17 00:00:00 2001 From: Mathias Vandaele Date: Tue, 17 Sep 2024 14:33:37 +0200 Subject: [PATCH 09/15] Update docs/components/connectors/out-of-the-box-connectors/email.md Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> --- docs/components/connectors/out-of-the-box-connectors/email.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/components/connectors/out-of-the-box-connectors/email.md b/docs/components/connectors/out-of-the-box-connectors/email.md index c106b8b929..8e8b020ccf 100644 --- a/docs/components/connectors/out-of-the-box-connectors/email.md +++ b/docs/components/connectors/out-of-the-box-connectors/email.md @@ -450,8 +450,8 @@ using an AND and OR operator to combine multiple conditions: "value": "urgent" }, { - "field":"SUBJECT", - "value":"important" + "field": "SUBJECT", + "value": "important" } ] } From bf31821ba73fb42f226cd1e971b2bba722e1787c Mon Sep 17 00:00:00 2001 From: Mathias Vandaele Date: Tue, 17 Sep 2024 14:33:44 +0200 Subject: [PATCH 10/15] Update docs/components/connectors/out-of-the-box-connectors/email.md Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> --- docs/components/connectors/out-of-the-box-connectors/email.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/components/connectors/out-of-the-box-connectors/email.md b/docs/components/connectors/out-of-the-box-connectors/email.md index 8e8b020ccf..e48229fec6 100644 --- a/docs/components/connectors/out-of-the-box-connectors/email.md +++ b/docs/components/connectors/out-of-the-box-connectors/email.md @@ -466,8 +466,8 @@ A simpler query without logical operators may look like this: ```json { - "field":"FROM", - "value":"example@camunda.com" + "field": "FROM", + "value": "example@camunda.com" } ``` From 52404cd9ce2e0e034dcca5a7892a36874363ff7a Mon Sep 17 00:00:00 2001 From: Mathias Vandaele Date: Tue, 17 Sep 2024 14:33:51 +0200 Subject: [PATCH 11/15] Update docs/components/connectors/out-of-the-box-connectors/email.md Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> --- docs/components/connectors/out-of-the-box-connectors/email.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/components/connectors/out-of-the-box-connectors/email.md b/docs/components/connectors/out-of-the-box-connectors/email.md index e48229fec6..d86553ed51 100644 --- a/docs/components/connectors/out-of-the-box-connectors/email.md +++ b/docs/components/connectors/out-of-the-box-connectors/email.md @@ -497,8 +497,8 @@ Returned Response: ```json [ - {"messageId":"MessageId", "subject":"Important"}, - {"messageId":"MessageId2", "subject":"Urgent"} + { "messageId": "MessageId", "subject": "Important" }, + { "messageId": "MessageId2", "subject": "Urgent" } ] ``` From cd57b9805be56e6ba2a69acae4a9bb91e359401a Mon Sep 17 00:00:00 2001 From: Mathias Vandaele Date: Tue, 17 Sep 2024 14:34:08 +0200 Subject: [PATCH 12/15] Update docs/components/connectors/out-of-the-box-connectors/email.md Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> --- docs/components/connectors/out-of-the-box-connectors/email.md | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/components/connectors/out-of-the-box-connectors/email.md b/docs/components/connectors/out-of-the-box-connectors/email.md index d86553ed51..54a7b3131f 100644 --- a/docs/components/connectors/out-of-the-box-connectors/email.md +++ b/docs/components/connectors/out-of-the-box-connectors/email.md @@ -527,7 +527,6 @@ Upon successful completion of the move operation, the response will contain a JS The example below demonstrates the expected JSON response after an email has been successfully moved: ```json - { "messageId":"VE1P191MB1101730EEA31B2FEAB320143919A2@VE1P191MB1101.EURP191.PROD.OUTLOOK.COM", "from":"INBOX", From c8852c9265318c65a9070b1145f45c5f050e46db Mon Sep 17 00:00:00 2001 From: Mathias Vandaele Date: Tue, 17 Sep 2024 14:41:23 +0200 Subject: [PATCH 13/15] Update docs/components/connectors/out-of-the-box-connectors/email.md Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> --- .../connectors/out-of-the-box-connectors/email.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/components/connectors/out-of-the-box-connectors/email.md b/docs/components/connectors/out-of-the-box-connectors/email.md index 54a7b3131f..5ae29ea9fb 100644 --- a/docs/components/connectors/out-of-the-box-connectors/email.md +++ b/docs/components/connectors/out-of-the-box-connectors/email.md @@ -528,9 +528,9 @@ The example below demonstrates the expected JSON response after an email has bee ```json { - "messageId":"VE1P191MB1101730EEA31B2FEAB320143919A2@VE1P191MB1101.EURP191.PROD.OUTLOOK.COM", - "from":"INBOX", - "to":"TEST" + "messageId": "VE1P191MB1101730EEA31B2FEAB320143919A2@VE1P191MB1101.EURP191.PROD.OUTLOOK.COM", + "from": "INBOX", + "to": "TEST" } ``` From 598487c2135c1ba353628dbae0b19fa454ed7738 Mon Sep 17 00:00:00 2001 From: Mathias Vandaele Date: Tue, 17 Sep 2024 14:47:29 +0200 Subject: [PATCH 14/15] docs(email-connector): prettier --- .../out-of-the-box-connectors/email.md | 140 +++++++++--------- 1 file changed, 68 insertions(+), 72 deletions(-) diff --git a/docs/components/connectors/out-of-the-box-connectors/email.md b/docs/components/connectors/out-of-the-box-connectors/email.md index 5ae29ea9fb..7a2309f19a 100644 --- a/docs/components/connectors/out-of-the-box-connectors/email.md +++ b/docs/components/connectors/out-of-the-box-connectors/email.md @@ -154,10 +154,9 @@ After the deletion task is performed, a JSON object is returned to confirm the a The following JSON response exemplifies the result of a successful deletion request: ```json - { - "deleted":true, - "messageId":"MessageId" + "deleted": true, + "messageId": "MessageId" } ``` @@ -174,22 +173,22 @@ using an AND and OR operator to combine multiple conditions: ```json { - "operator":"AND", - "criteria":[ + "operator": "AND", + "criteria": [ { - "field":"FROM", - "value":"example@camunda.com" + "field": "FROM", + "value": "example@camunda.com" }, { - "operator":"OR", - "criteria":[ + "operator": "OR", + "criteria": [ { - "field":"SUBJECT", - "value":"urgent" + "field": "SUBJECT", + "value": "urgent" }, { - "field":"SUBJECT", - "value":"important" + "field": "SUBJECT", + "value": "important" } ] } @@ -204,8 +203,8 @@ A simpler query without logical operators may look like this: ```json { - "field":"FROM", - "value":"example@camunda.com" + "field": "FROM", + "value": "example@camunda.com" } ``` @@ -235,8 +234,8 @@ Returned Response: ```json [ - {"messageId":"MessageId", "subject":"Important"}, - {"messageId":"MessageId2", "subject":"Urgent"} + { "messageId": "MessageId", "subject": "Important" }, + { "messageId": "MessageId2", "subject": "Urgent" } ] ``` @@ -283,8 +282,8 @@ Here's an example of a successful email-sending operation: ```json { - "subject":"Example Subject", - "sent":true + "subject": "Example Subject", + "sent": true } ``` @@ -309,11 +308,11 @@ options. number of emails the task will return. - `Sort emails by`: Choose the field by which to sort the emails. The currently supported sorting fields are: - - `Sent date`: Sorts emails by the date and time they were sent. - - `Size`: Sorts emails by the size of the email. + - `Sent date`: Sorts emails by the date and time they were sent. + - `Size`: Sorts emails by the size of the email. - `Sort order`: Define the sort order using either: - - `ASC`: Ascending order, from the oldest or smallest value to the most recent or largest. - - `DESC`: Descending order, from the most recent or largest value to the oldest or smallest. + - `ASC`: Ascending order, from the oldest or smallest value to the most recent or largest. + - `DESC`: Descending order, from the most recent or largest value to the oldest or smallest. - `Folder`: (Optional) the folder to list emails from, default is `INBOX`. ### Sorting and Limiting Behavior @@ -338,18 +337,18 @@ Example of a returned JSON array: ```json [ { - "messageId":"RandomId", - "fromAddresses":["msa@communication.microsoft.com"], - "subject":"Example", - "size":99865 - }, { - "messageId":"RandomId2", - "fromAddresses":["example@camunda.com"], - "subject":"Example", - "size":48547 + "messageId": "RandomId", + "fromAddresses": ["msa@communication.microsoft.com"], + "subject": "Example", + "size": 99865 + }, + { + "messageId": "RandomId2", + "fromAddresses": ["example@camunda.com"], + "subject": "Example", + "size": 48547 } ] - ``` ## Read Email @@ -379,14 +378,12 @@ The following JSON structure illustrates the expected response after a successfu ```json { - "messageId":"MessageId", - "fromAddresses":[ - "example@camunda.com" - ], - "subject":"Example Subject", - "size":99865, - "plainTextBody":"Any text content", - "htmlBody":"Any Html Content" + "messageId": "MessageId", + "fromAddresses": ["example@camunda.com"], + "subject": "Example Subject", + "size": 99865, + "plainTextBody": "Any text content", + "htmlBody": "Any Html Content" } ``` @@ -412,10 +409,9 @@ The task provides a JSON object in the response, indicating the outcome of the d Here is an example of the JSON response that confirms the successful deletion of an email: ```json - { - "deleted":true, - "messageId":"MessageId" + "deleted": true, + "messageId": "MessageId" } ``` @@ -436,15 +432,15 @@ using an AND and OR operator to combine multiple conditions: ```json { - "operator":"AND", - "criteria":[ + "operator": "AND", + "criteria": [ { - "field":"FROM", - "value":"example@camunda.com" + "field": "FROM", + "value": "example@camunda.com" }, { - "operator":"OR", - "criteria":[ + "operator": "OR", + "criteria": [ { "field": "SUBJECT", "value": "urgent" @@ -560,22 +556,22 @@ This inbound connector will create a new process each time a new email will be r - `Folder`: (Optional) Specifies the folder that the inbound connector should monitor. The default folder is INBOX. - `Sync Strategy`: Determines how emails are synchronized when the connector starts: - - `Unseen emails will be sync`: A process instance is created for every unseen email present in the folder at the - time the connector starts. - - `No initial sync. Only new emails`: The connector skips past emails and starts listening for new emails arriving - in the folder. - - `All emails will be sync`: A process instance is created for every email in the folder, regardless of their read - status, when the connector starts. + - `Unseen emails will be sync`: A process instance is created for every unseen email present in the folder at the + time the connector starts. + - `No initial sync. Only new emails`: The connector skips past emails and starts listening for new emails arriving + in the folder. + - `All emails will be sync`: A process instance is created for every email in the folder, regardless of their read + status, when the connector starts. - `Handling Strategy`: Defines how emails are handled after processing: - - `Mark as read after processing`: Emails that have been processed will be marked as read. - - `Do nothing`: No action will be taken on processed emails. - - `Delete after processing`: Emails that have been processed will be deleted from the folder. - - `Move to another folder after processing`: Processed emails will be moved to another specified folder. - - `Folder`: Indicates the destination folder where emails will be moved after processing. A new folder or folder - hierarchy - can be specified using a dot-separated path (e.g., 'Archive' or 'Projects.2023.January'). Non-existent folders - in the - path will be created automatically. + - `Mark as read after processing`: Emails that have been processed will be marked as read. + - `Do nothing`: No action will be taken on processed emails. + - `Delete after processing`: Emails that have been processed will be deleted from the folder. + - `Move to another folder after processing`: Processed emails will be moved to another specified folder. + - `Folder`: Indicates the destination folder where emails will be moved after processing. A new folder or folder + hierarchy + can be specified using a dot-separated path (e.g., 'Archive' or 'Projects.2023.January'). Non-existent folders + in the + path will be created automatically. ### Example Response @@ -584,12 +580,12 @@ instance: ```json { - "messageId":"messageId", - "fromAddresses":["example@camunda.com"], - "subject":"Urgent Test", - "size":65646, - "plainTextBody":"Hey how are you?\r\n", - "htmlBody":"Hello" + "messageId": "messageId", + "fromAddresses": ["example@camunda.com"], + "subject": "Urgent Test", + "size": 65646, + "plainTextBody": "Hey how are you?\r\n", + "htmlBody": "Hello" } ``` @@ -616,7 +612,7 @@ To ignore messages that do not meet the activation condition and still handle th events** checkbox. | **Consume unmatched events** checkbox | Activation condition | Outcome | -|---------------------------------------|----------------------|--------------------------------------------------------------| +| ------------------------------------- | -------------------- | ------------------------------------------------------------ | | Checked | Matched | Connector is triggered, handling strategy is applied | | Unchecked | Matched | Connector is triggered, handling strategy is applied | | Checked | Unmatched | Connector is not triggered, handling strategy is applied | From 67a6d86b773ff420e17788c37957db08c0ee8412 Mon Sep 17 00:00:00 2001 From: Mathias Vandaele Date: Tue, 17 Sep 2024 16:14:32 +0200 Subject: [PATCH 15/15] docs(email-connector): fix comments --- .../out-of-the-box-connectors/email.md | 150 ++++++++++-------- 1 file changed, 82 insertions(+), 68 deletions(-) diff --git a/docs/components/connectors/out-of-the-box-connectors/email.md b/docs/components/connectors/out-of-the-box-connectors/email.md index 7a2309f19a..4e614f4f70 100644 --- a/docs/components/connectors/out-of-the-box-connectors/email.md +++ b/docs/components/connectors/out-of-the-box-connectors/email.md @@ -16,21 +16,28 @@ values={[{label: 'Email Outbound Connector', value: 'outbound' }, {label: 'Email The **Email Connector** is an outbound Connector that allows you to connect your BPMN service with any email POP3, IMAP or SMTP server. -# Prerequisites +## Prerequisites To use the **Email Connector**, you need to have an SMTP, POP3 or IMAP server available. Use Camunda secrets to avoid exposing your sensitive data as plain text. Follow our documentation on [managing secrets](/components/console/manage-clusters/manage-secrets.md) to learn more. -# Authentication +## Authentication As of now, there is two different ways to authenticate to a mail server. -## Simple Authentication +### Simple Authentication It allows the user to connect to any SMTP, POP3 or IMAP server using the email address and the associated password. -# POP3 +#### Parameters + +- `username`: Enter your full email address (e.g., user@example.com) or the username provided by your email service. + This is used to authenticate your access to the mail server. +- `password`: Enter the password associated with your email account. Keep your password secure and do not share it with + others. + +## POP3 The Post Office Protocol version 3 (POP3) is an Internet standard protocol used by local email clients to retrieve emails from a remote server over a TCP/IP connection. POP3 allows users to download messages from their email server to @@ -42,9 +49,9 @@ simple download-and-delete model, meaning emails are typically removed from the - `Cryptographic protocol`: It defines how the connection to the server should be secured, TLS, SSL or None. Default is typically TLS. -## List Emails +### List Emails -### Parameters +#### Parameters This feature allows users to fetch a list of emails from the `INBOX` folder with customizable sorting and limitation options. @@ -59,13 +66,13 @@ options. - `ASC`: Ascending order, from the oldest or smallest value to the most recent or largest. - `DESC`: Descending order, from the most recent or largest value to the oldest or smallest. -### Sorting and Limiting Behavior +#### Sorting and Limiting Behavior Emails are initially sorted based on the specified sorting field and order. The list is then limited to the number of emails as defined by the Max Emails to read parameter. For example, if you sort by Sent date in descending order (DESC) with a limit of one email, the task will return the most recently sent email. -### Response Structure +#### Response Structure The task returns a list of emails in JSON format. Each email object contains the following information: @@ -74,7 +81,7 @@ The task returns a list of emails in JSON format. Each email object contains the - `subject`: The subject line of the email. - `size`: The size of the email in bytes. -### Example Response +#### Example Response Example of a returned JSON array: @@ -95,18 +102,18 @@ Example of a returned JSON array: ] ``` -## Read Email +### Read Email This functionality retrieves the contents of an email by using the unique `messageId` associated with the email message. -### Parameters +#### Parameters - `MessageId`: This is the identifier of the email message you wish to read. It should be provided to locate and return the specific email. - `Delete after reading`: This is a boolean parameter. If set to true, the email will be deleted from the server after it has been read. If false or not set, the email will remain on the server. -### Response Structure +#### Response Structure Upon successful execution of the task, the response will be a JSON object containing detailed information about the email: @@ -118,7 +125,7 @@ email: - `plainTextBody`: The plain text version of the email body. - `htmlBody`: The HTML version of the email body, if available. -### Example Response +#### Example Response Below is an example of the JSON response returned when a specific email is read: @@ -133,23 +140,23 @@ Below is an example of the JSON response returned when a specific email is read: } ``` -## Delete Email +### Delete Email This operation facilitates the removal of an email from the server using the specific `messageId` assigned to the email message. -### Parameters +#### Parameters - `MessageId`: The unique identifier of the email message that needs to be deleted. -### Response Structure +#### Response Structure After the deletion task is performed, a JSON object is returned to confirm the action: - `deleted`: A boolean value that indicates whether the deletion was successful (true) or not (false). - `messageId`: The identifier of the email message that was attempted to be deleted. -### Example Response +#### Example Response The following JSON response exemplifies the result of a successful deletion request: @@ -160,13 +167,13 @@ The following JSON response exemplifies the result of a successful deletion requ } ``` -## Search Emails +### Search Emails This feature enables users to perform advanced searches within an email inbox by constructing a criteria-based query using a JSON object. The search functionality supports complex queries that can combine multiple conditions using logical operators. -### Parameters +#### Parameters A search query is represented as a JSON object. Below is an example of a JSON object that represents a search criteria using an AND and OR operator to combine multiple conditions: @@ -223,12 +230,12 @@ When using an operator such as AND or OR, you must also define a criteria array. conditions that the search will evaluate against the emails. Each condition within the criteria array is itself a JSON object with a field and a value. -#### Notes +##### Notes - If an operator is set, the criteria array must also be defined. - Each criterion within the criteria array is applied to the specified field based on the value associated with it. -### Example Response +#### Example Response Returned Response: @@ -239,7 +246,7 @@ Returned Response: ] ``` -# SMTP +## SMTP Simple Mail Transfer Protocol (SMTP) is the standard communication protocol for sending emails across the Internet. It facilitates mail transfer from a client's email application to the outgoing mail server and between servers for relaying @@ -251,11 +258,11 @@ the receiving server for delivery to the appropriate mailbox. - `Cryptographic protocol`: It defines how the connection to the server should be secured, TLS, SSL or None. Default is typically TLS. -## Send Email +### Send Email This task enables users to send an email from the connected email account. -### Parameters +#### Parameters - `From`: Specifies the sender's email address(es). This can be a single email address (e.g., 'example@camunda.com'), a comma-separated list of addresses, or a Friendly Enough Expression Language (FEEL) expression returning a list of @@ -269,14 +276,14 @@ This task enables users to send an email from the connected email account. - `Subject`: The subject line of the email. - `Email` Content: The main content of the email. -### Response Structure +#### Response Structure Upon successfully sending the email, the following JSON response is returned: - `subject`: Echoes back the subject of the sent email. - `sent`: A boolean value indicating the success status of the email being sent (true for success, false for failure). -### Example Response +#### Example Response Here's an example of a successful email-sending operation: @@ -290,19 +297,19 @@ Here's an example of a successful email-sending operation: In this response, `sent: true` confirms that the email with the specified subject "Example Subject" has been successfully dispatched. If the email fails to send, "sent" would be false -# IMAP +## IMAP The Internet Message Access Protocol (IMAP) is a protocol used by email clients to access messages stored on a mail server, allowing users to view and manage their emails from multiple devices. Unlike POP3, IMAP supports both online and offline modes, synchronizes email across devices, and allows manipulation of mailboxes (create, delete, and rename) as well as messages (read, delete, or flag) directly on the server. -## List Emails +### List Emails This feature allows users to fetch a list of emails from a given with customizable sorting and limitation options. -### Parameters +#### Parameters - `Max Emails to read`: Specify the maximum number of emails to retrieve. This parameter determines the cap on the number @@ -315,13 +322,13 @@ options. - `DESC`: Descending order, from the most recent or largest value to the oldest or smallest. - `Folder`: (Optional) the folder to list emails from, default is `INBOX`. -### Sorting and Limiting Behavior +#### Sorting and Limiting Behavior Emails are initially sorted based on the specified sorting field and order. The list is then limited to the number of emails as defined by the Max Emails to read parameter. For example, if you sort by Sent date in descending order (DESC) with a limit of one email, the task will return the most recently sent email. -### Response Structure +#### Response Structure The task returns a list of emails in JSON format. Each email object contains the following information: @@ -330,7 +337,7 @@ The task returns a list of emails in JSON format. Each email object contains the - `subject`: The subject line of the email. - `size`: The size of the email in bytes. -### Example Response +#### Example Response Example of a returned JSON array: @@ -351,17 +358,17 @@ Example of a returned JSON array: ] ``` -## Read Email +### Read Email This task is designed to retrieve an email's details based on the provided `messageId`. -### Parameters +#### Parameters - `MessageId`: This parameter requires the unique identifier of the email that needs to be read. - `Folder`: (Optional) Specifies the folder from which the email should be retrieved. If not provided, the default folder is `INBOX`. -### Response Structure +#### Response Structure The task returns a JSON object with detailed information about the email: @@ -372,7 +379,7 @@ The task returns a JSON object with detailed information about the email: - `plainTextBody`: The plain text version of the email's content. - `htmlBody`: The HTML version of the email's content, provided it exists. -### Example Response +#### Example Response The following JSON structure illustrates the expected response after a successful email retrieval: @@ -387,24 +394,24 @@ The following JSON structure illustrates the expected response after a successfu } ``` -## Delete Email +### Delete Email This task facilitates the deletion of an email from a specified folder using the email's unique `messageId`. -### Parameters +#### Parameters - `MessageId`: The identifier of the email message to be deleted. - `Folder`: (Optional) Specifies the folder from which the email should be deleted. If this parameter is not supplied, the default folder is assumed to be `INBOX`. -### Response Structure +#### Response Structure The task provides a JSON object in the response, indicating the outcome of the deletion request: - `deleted`: A boolean value that signifies whether the email was successfully deleted (true) or not (false). - `messageId`: Reiterates the messageId of the email that was targeted for deletion. -### Example Response +#### Example Response Here is an example of the JSON response that confirms the successful deletion of an email: @@ -415,13 +422,13 @@ Here is an example of the JSON response that confirms the successful deletion of } ``` -## Search Emails +### Search Emails This feature enables users to perform advanced searches within an email inbox by constructing a criteria-based query using a JSON object. The search functionality supports complex queries that can combine multiple conditions using logical operators. -### Parameters +#### Parameters A search query is represented as a JSON object. Below is an example of a JSON object that represents a search criteria using an AND and OR operator to combine multiple conditions: @@ -482,12 +489,12 @@ When using an operator such as AND or OR, you must also define a criteria array. conditions that the search will evaluate against the emails. Each condition within the criteria array is itself a JSON object with a field and a value. -#### Notes +##### Notes - If an operator is set, the criteria array must also be defined. - Each criterion within the criteria array is applied to the specified field based on the value associated with it. -### Example Response +#### Example Response Returned Response: @@ -498,11 +505,11 @@ Returned Response: ] ``` -## Move Email +### Move Email This task enables users to transfer an email from one folder to another, streamlining inbox organization. -### Parameters +#### Parameters - `MessageId`: The identifier of the email that needs to be moved. - `Source folder`: (Optional) The folder from which the email will be moved. If not specified, the default is INBOX. @@ -510,7 +517,7 @@ This task enables users to transfer an email from one folder to another, streaml use a dot-separated path (e.g., 'Archive' or 'Projects.2023.January'). The system will automatically create any non-existing folders in the path. -### Response Structure +#### Response Structure Upon successful completion of the move operation, the response will contain a JSON object with the following details: @@ -518,7 +525,7 @@ Upon successful completion of the move operation, the response will contain a JS - `from`: The source folder from which the email was moved. - `to`: The target folder to which the email has been moved. -### Example Response +#### Example Response The example below demonstrates the expected JSON response after an email has been successfully moved: @@ -534,23 +541,32 @@ The example below demonstrates the expected JSON response after an email has bee -# Prerequisites +## Prerequisites +:::warning This inbound connector only work with IMAP server. +::: To use the **Email Inbound Connector**, you need to have an IMAP server available. Use Camunda secrets to avoid exposing your sensitive data as plain text. Follow our documentation on [managing secrets](/components/console/manage-clusters/manage-secrets.md) to learn more. -# Authentication +## Authentication As of now, there is two different ways to authenticate to a mail server. -## Simple Authentication +### Simple Authentication It allows the user to connect to any IMAP server using the email address and the associated password. -## Listener information's +#### Parameters + +- `username`: Enter your full email address (e.g., user@example.com) or the username provided by your email service. + This is used to authenticate your access to the mail server. +- `password`: Enter the password associated with your email account. Keep your password secure and do not share it with + others. + +### Listener information's This inbound connector will create a new process each time a new email will be received. @@ -573,7 +589,7 @@ This inbound connector will create a new process each time a new email will be r in the path will be created automatically. -### Example Response +#### Example Response The JSON response below is an example of the data structure produced when an email triggers the creation of a process instance: @@ -593,20 +609,23 @@ This response includes essential email details such as the messageId, sender add of the email both in plain text and HTML format. This information can be used by the process for various workflows, such as prioritizing tasks, content analysis, and automated responses. -### Activation condition +#### Activation condition -The **Activation condition** is an optional field where you can specify a Friendly Enough Expression Language (FEEL) +The **Activation condition** is an optional field where you can specify a Friendly Enough Expression Language [ +FEEL](https://docs.camunda.io/docs/components/modeler/feel/what-is-feel/) expression to control when the Email Inbound Connector should trigger a process instance. This condition acts as a filter, allowing the process to be initiated only when certain criteria are met by the incoming email. -#### Example Usage +##### Example Usage For instance, the FEEL expression =(response.subject = "urgent") will ensure that the process is only triggered if the subject of the incoming email matches "urgent". If this field is left blank, the process will be triggered for every email received by the connector. -:::warning By default, the Email Inbound Connector is designed not to execute its handling strategy if it encounters an -email that it cannot process, such as when the activation condition is not fulfilled. ::: +:::warning +By default, the Email Inbound Connector is designed not to execute its handling strategy if it encounters an +email that it cannot process, such as when the activation condition is not fulfilled. +::: To ignore messages that do not meet the activation condition and still handle the email, check the **Consume unmatched events** checkbox. @@ -618,16 +637,11 @@ events** checkbox. | Checked | Unmatched | Connector is not triggered, handling strategy is applied | | Unchecked | Unmatched | Connector is not triggered, handling strategy is not applied | -### Correlation +#### Correlation The **Correlation** section allows you to configure the message correlation parameters. -:::note -The **Correlation** section is not applicable for the plain **start event** element template of the email Connector. -Plain **start events** are triggered by process instance creation and do not rely on message correlation. -::: - -#### Correlation key +##### Correlation key - **Correlation key (process)** is a FEEL expression that defines the correlation key for the subscription. This corresponds to the **Correlation key** property of a regular **message intermediate catch event**. @@ -644,7 +658,7 @@ You can also use the key of the message to accomplish this in the **Correlation Learn more about correlation keys in the [messages guide](../../../concepts/messages). -#### Message ID expression +##### Message ID expression The **Message ID expression** is an optional field that allows you to extract the message ID from the incoming message. The message ID serves as a unique identifier for the message and is used for message correlation. @@ -662,7 +676,7 @@ can configure the **Message ID expression** as follows: = message.messageId ``` -#### Message TTL +##### Message TTL The **Message TTL** is an optional field that allows you to set the time-to-live (TTL) for the correlated messages. TTL defines the time for which the message is buffered in Zeebe before being correlated to the process instance (if it can't @@ -670,7 +684,7 @@ be correlated immediately). The value is specified as an ISO 8601 duration. For example, `PT1H` sets the TTL to one hour. Learn more about the TTL concept in Zeebe in the [message correlation guide](../../../concepts/messages#message-buffering). -### Deduplication +#### Deduplication The **Deduplication** section allows you to configure the Connector deduplication parameters. Not to be confused with **message deduplication**, **Connector deduplication** is a mechanism in the Connector Runtime