Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Docs new features email #4730

Merged
merged 4 commits into from
Dec 12, 2024
Merged

Docs new features email #4730

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
2372640
docs(email-connector): add documentation for the new email's features
mathias-vandaele Dec 9, 2024
62fc4ac
docs(email-connector): add documentation for the new email's features
mathias-vandaele Dec 9, 2024
064edaa
TW edits
mesellings Dec 12, 2024
127bac8
Merge branch 'main' into docs-new-features-email
mesellings Dec 12, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
92 changes: 72 additions & 20 deletions docs/components/connectors/out-of-the-box-connectors/email.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -73,7 +73,7 @@ with a limit of one email, the task will return the most recently sent email.
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.
- `fromAddress`: the email addresses of the sender.
- `fromAddress`: The email addresses of the sender.
- `subject`: The subject line of the email.
- `size`: The size of the email (in bytes).

Expand Down Expand Up @@ -117,13 +117,14 @@ Reading an email using POP3 protocol will delete the email
The task returns a JSON object containing detailed information about the email:

- `messageId`: The unique identifier corresponding to the email message.
- `fromAddress`: the email addresses of the sender.
- `fromAddress`: The email addresses of the sender.
- `headers` : A list containing the email's headers
- `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.
- `receivedDateTime`: the email's reception datetime
- `htmlBody`: The HTML version of the email's content (if content exists).
- `attachments`: A list of all the email's attachments, provided as a document reference.
- `receivedDateTime`: The email's reception datetime

#### Example Response

Expand All @@ -147,7 +148,19 @@ Below is an example of the JSON response returned when a specific email is read:
"value": "test"
}
],
"sentDate": "2024-08-19T06:54:28Z"
"attachments": [
{
"storeId": "in-memory",
"documentId": "20f1fd6a-d8ea-403b-813c-e281c1193495",
"metadata": {
"contentType": "image/webp; name=305a4816-b3df-4724-acd3-010478a54add.webp",
"size": 311032,
"fileName": "305a4816-b3df-4724-acd3-010478a54add.webp"
},
"documentType": "camunda"
}
],
"receivedDateTime": "2024-08-19T06:54:28Z"
}
```

Expand Down Expand Up @@ -278,14 +291,18 @@ Allow users to send an email from the connected email account.

#### Parameters

| Parameter | Description |
| :-------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `From` | Specify the sender's email address(es). This can be a single email address (for example, '[email protected]'), a comma-separated list of addresses, or a Friendly Enough Expression Language (FEEL) expression returning a list of email addresses (for example, =["[email protected]"]). |
| `To` | Defines the email recipient(s). Similar to the `From` parameter, this can be a single email address, a comma-separated list, or a FEEL expression (for example, =["[email protected]"]). |
| `Cc` | (Optional) Specify the email address(es) to include in the **Carbon Copy (CC)** 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) Specify the email address(es) to include in the **Blind Carbon Copy (BCC)** field. It follows the same format as the **CC** field and ensures that BCC recipients are not visible to other recipients. |
| `Subject` | The email subject line. |
| `Email` | The main content of the email. |
| Parameter | Description |
| :------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `From` | Specify the sender's email address(es). This can be a single email address (for example, '[email protected]'), a comma-separated list of addresses, or a Friendly Enough Expression Language (FEEL) expression returning a list of email addresses (for example, =["[email protected]"]). |
| `To` | Defines the email recipient(s). Similar to the `From` parameter, this can be a single email address, a comma-separated list, or a FEEL expression (for example, =["[email protected]"]). |
| `Cc` | (Optional) Specify the email address(es) to include in the **Carbon Copy (CC)** 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) Specify the email address(es) to include in the **Blind Carbon Copy (BCC)** field. It follows the same format as the **CC** field and ensures that BCC recipients are not visible to other recipients. |
| `Headers` | Feel expression containing all the desired headers to be added to the email's headers. cf. `{ "customHeaders" : "new header value" }` |
| `Subject` | The email subject line. |
| `Content Type` | The content type of the email. |
| `Email Text Content` | The text content of the email. This must only be provided if the `Content Type` is `PLAIN` or `HTML & PlainText`. |
| `Html Text Content` | The HTML content of the email. This must only be provided if the `Content Type` is `HTML` or `HTML & PlainText`. |
| `Attachment` | The document reference, either for a single document or as a list for multiple documents. |

:::info
To learn more about Friendly Enough Expression Language (FEEL) expression,
Expand Down Expand Up @@ -401,6 +418,7 @@ The task returns a JSON object containing detailed information about the email:
- `size`: The size of the email (in bytes).
- `plainTextBody`: The plain text version of the email content.
- `htmlBody`: The HTML version of the email content, if it exists.
- `attachments`: A list of all the email's attachments, provided as a document reference.
- `receivedDateTime`: The date and time the email was received.

#### Example Response
Expand All @@ -425,7 +443,19 @@ The following JSON structure shows an expected response after a successful email
"value": "test"
}
],
"sentDate": "2024-08-19T06:54:28Z"
"attachments": [
{
"storeId": "in-memory",
"documentId": "20f1fd6a-d8ea-403b-813c-e281c1193495",
"metadata": {
"contentType": "image/webp; name=305a4816-b3df-4724-acd3-010478a54add.webp",
"size": 311032,
"fileName": "305a4816-b3df-4724-acd3-010478a54add.webp"
},
"documentType": "camunda"
}
],
"receivedDateTime": "2024-08-19T06:54:28Z"
}
```

Expand Down Expand Up @@ -578,7 +608,8 @@ The example below shows the expected JSON response after an email has been succe

<TabItem value='inbound'>

The Email Inbound Connector is an inbound Connector that allows you to connect your BPMN service with any email IMAP server.
The Email Inbound Connector is an inbound Connector that allows you to connect your BPMN service with any email IMAP
server.

:::caution
This inbound connector only supports working with IMAP server.
Expand Down Expand Up @@ -629,6 +660,7 @@ The task returns a JSON object containing detailed information about the email:
- `size`: The size of the email (in bytes).
- `plainTextBody`: The plain text version of the email content.
- `htmlBody`: The HTML version of the email content, if it exists.
- `attachments` A list of document reference
- `receivedDateTime`: The date and time the email was received.

#### Example Response
Expand All @@ -654,7 +686,19 @@ instance:
"value": "test"
}
],
"sentDate": "2024-08-19T06:54:28Z"
"attachments": [
{
"storeId": "in-memory",
"documentId": "20f1fd6a-d8ea-403b-813c-e281c1193495",
"metadata": {
"contentType": "image/webp; name=305a4816-b3df-4724-acd3-010478a54add.webp",
"size": 311032,
"fileName": "305a4816-b3df-4724-acd3-010478a54add.webp"
},
"documentType": "camunda"
}
],
"receivedDateTime": "2024-08-19T06:54:28Z"
}
```

Expand All @@ -664,9 +708,14 @@ as prioritizing tasks, content analysis, and automated responses.

## Activation condition

The optional **Activation condition** field allows you to specify a Friendly Enough Expression Language ([FEEL](/components/modeler/feel/what-is-feel.md)) expression to control when this 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.
The optional **Activation condition** field allows you to specify a Friendly Enough Expression
Language ([FEEL](/components/modeler/feel/what-is-feel.md)) expression to control when this 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.

For example, the FEEL expression `=(response.subject = "urgent")` ensures that the process is only triggered if the subject of the incoming email matches "urgent". If this field is left blank, the process is triggered for every email received by the connector.
For example, the FEEL expression `=(response.subject = "urgent")` ensures that the process is only triggered if the
subject of the incoming email matches "urgent". If this field is left blank, the process is triggered for every email
received by the connector.

## Correlation

Expand Down Expand Up @@ -729,9 +778,12 @@ To learn more about TTL in Zeebe, see [message correlation](../../../concepts/me

The **Deduplication** section allows you to configure the Connector deduplication parameters.

- **Connector deduplication** is a mechanism in the Connector Runtime that determines how many email listeners are created if there are multiple occurrences of the **Email Listener Connector** in a BPMN diagram. This is different to **message deduplication**.
- **Connector deduplication** is a mechanism in the Connector Runtime that determines how many email listeners are
created if there are multiple occurrences of the **Email Listener Connector** in a BPMN diagram. This is different to
**message deduplication**.

- By default, the Connector runtime deduplicates Connectors based on properties, so elements with the same subscription properties only result in one subscription.
- By default, the Connector runtime deduplicates Connectors based on properties, so elements with the same subscription
properties only result in one subscription.

To customize the deduplication behavior, select the **Manual mode** checkbox and configure the custom deduplication ID.

Expand Down
Loading