Skip to content

Commit

Permalink
Docs new features email (#4730)
Browse files Browse the repository at this point in the history 
* docs(email-connector): add documentation for the new email's features

* docs(email-connector): add documentation for the new email's features

* TW edits

---------

Co-authored-by: mesellings <mark.sellings@camunda.com>
  • Loading branch information
@mathias-vandaele @mesellings
mathias-vandaele and mesellings authored Dec 12, 2024
1 parent 688013b commit 2ee5140
Showing 1 changed file with 72 additions and 20 deletions.
92 changes: 72 additions & 20 deletions docs/components/connectors/out-of-the-box-connectors/email.md
View file
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, 'example@camunda.com'), a comma-separated list of addresses, or a Friendly Enough Expression Language (FEEL) expression returning a list of email addresses (for example, =["example@camunda.com"]). |
| `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, =["example@camunda.com"]). |
| `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, 'example@camunda.com'), a comma-separated list of addresses, or a Friendly Enough Expression Language (FEEL) expression returning a list of email addresses (for example, =["example@camunda.com"]). |
| `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, =["example@camunda.com"]). |
| `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

0 comments on commit 2ee5140

Please sign in to comment.