Mail
The ThingWorx Mail extension provides the ability to read and send emails from ThingWorx through external SMTP mail servers that are made available to it. You can create one or more mail Things in ThingWorx to store configuration information used to send emails.
The services provided by the Mail extension can be used directly or in conjunction with the ThingWorx Notifications feature. The ThingWorx Mail extension is available on support.ptc.com under Download software > Order or Download Software Updates > ThingWorx Foundation > Release (latest version) > ThingWorx Mail Extension > Most Recent Version > Mail-Extensions.
 |
Make sure that you have a FileRepository Thing where email attachments can be stored.
|
|
|
A valid email address must contain an @ character. For example, someone@company.com. If this format is not used, an error will be displayed. If the email address contains an @ character but not a period, it is also considered a valid email. For example, someone@companycom.
|
Configuration
You need to import the Mail_extension.zip extension to ThingWorx. After importing the Mail extension, a Thing Template named MailServer appears in the Thing Templates list.
To create and configure a new Mail Thing, do the following:
|
|
Starting with Mail Extension 4.1.1, if the ignoreTrustedDomains is set to True, then the SMTP Server and POP3 Server address must be updated in the MailServer Thing Template before creating a Thing. The SMTP Server and POP3 Server address should be present in the trustedDomains list of the DomainConfiguration in the platform-settings.json file.
|
1. In ThingWorx, create a new Thing and assign the MailServer Thing Template.
2. Click the Configuration view.
The following screen appears: 
| | The default values in these fields above are examples. Change them as needed for your organization. |
3. Enter the following details used to connect to the SMTP server:
| | As many of these settings are dependent on how the server is set up, contact your administrator or see documentation associated with the server to determine the proper settings. |
| | In Mail Extension 4.1.1 or later, you can configure HTTP and HTTPS proxies using the following JVM options: • http.proxyHost or https.proxyHost sets the host name of the proxy server. • http.proxyPort or https.proxyPort sets the port number of the proxy server. For more information on proxies, see Java Networking and Proxies. |
JDBC Settings | Description | ||
SMTP Server | Starting with Mail Extension 4.1.1, the address of the server from which emails are sent, the address should be present in the trustedDomains list of the DomainConfiguration in the platform-settings.json file.
| ||
SMTP Server Port | Port through which ThingWorx logs in to the mail server to send emails | ||
POP3 Server | Starting with Mail Extension 4.1.1, the address of the server from which emails are sent, the address should be present in the trustedDomains list of the DomainConfiguration in the platform-settings.json file.
| ||
POP3 Server Port | Port through which ThingWorx logs in to the mail server to check and retrieve emails | ||
Use TLS | Indicates whether to use TLS (Transport Layer Security) | ||
Use SSL | Indicates whether to use SSL (Secure Sockets Layer) | ||
Mail Account User | The user name for the email account that is used to send and retrieve emails on the given mail server. This is different than the from field value, which is used for the sender address when sending emails. The from field value needs to be a valid email account. | ||
Mail Account Password | The password for the email account. For Gmail (and in other cases), the specified email account can be updated to allow less secure app sign-in (see KCS Article CS200624). | ||
Default From Field | Refers to the email address to use as the from address when no address is specified when invoking the SendMessage services. This is primarily used when sending Notifications emails. | ||
Connection Timeout | Refers to how long ThingWorx should wait while trying to log in to the mail server before throwing an exception. The time should be entered in milliseconds. | ||
Operation Timeout | Refers to how long ThingWorx should remain open without reading any data. The time should be entered in milliseconds. | ||
Socks Host | The host name of a SOCKS proxy server if used with the mail server.
| ||
Socks Port | The port through which ThingWorx connects to the SOCKS proxy server, if used. | ||
Attachment File Repository | The name of the FileRepository Thing to use for processing attachments when reading emails from the mail server. | ||
No-Reply Address | The address for sending an email from an anonymous or generic address. No reply emails are allowed to this address.
| ||
Reply Address | The address to which an email recipient would reply. If the email recipient replies to an email that you have sent, the email address that you have set in Reply Address field will appear. | ||
Error Address | The address to receive emails notifying of recipients that do not exist.
The sender of the notification email would be either the address that you have set in No-Reply Address or, if it is not set, then the mail account user. No notification is sent when the recipient’s email address is correct. Also, notifications are only sent for incorrect email addresses and not for invalid user accounts. For example, if thingworx@ptc.com is an invalid account, then there will not be any automated notification. |
Password Reset Parameters: Only applicable if you are resetting a form login password. The following parameter values are used to create the reset URL for users. If the ThingWorx instance is behind a reverse proxy, then the URL will be accessible for users.
Parameter | Description |
|---|---|
Platform Proxy Scheme | http/https for the proxy machine. |
Platform Proxy Host | Host name for the proxy machine. |
Platform Proxy Port | The port on which the proxy service is running on the proxy machine. |
4. To test the settings, click Save, and then select the Services area.
5. Click SendMessage, and then enter the following details:
◦ from — the valid email address of the sender (for example, as donotreply@domain.com)
◦ to — valid email address specifying the recipient of the email.
◦ subject — the subject of the email.
◦ body — the content of the email (this is an XML parameter).
6. Click Execute.
7. Check if an email is received by the email address specified in the to field.
If the email is not received, check out the troubleshooting tips in KCS Article CS236135.
8. Click SendMessageWithNoReplyTo, and then enter the following details:
◦ to — valid email address specifying the recipient of the email.
◦ subject — the subject of the email.
◦ body — the content of the email (this is an XML parameter).
9. Click Execute.
| | This will send an email from the default address you entered in the No-Reply Address field. |
10. Click SendMessageWithAttachment and then enter the following details:
| | Use this service only when you have a single attachment with the email. Use SendMessageWithAttachments when you want to attach more than one file with the email. |
◦ from — the valid email address of the sender (for example, as donotreply@domain.com)
◦ to — valid email address specifying the recipient of the email.
◦ cc — valid email address specifying any other recipient to whom the email should be copied.
◦ bcc — valid email address specifying any other recipient to whom the email should be copied and without being visible to other recipients.
◦ subject — the subject of the email.
◦ body — the content of the email (this is an XML parameter).
◦ fileRepository — the repository in which the email attachments are stored.
◦ path — the path of the file to be attached.
| | If you have stored the attachment in ThingworxStorage/repository/FileRepository, you can directly give the name of the file in this field. For example, if the file name is Testfile.pdf, then you can enter this name as it is in this field. |
◦ attachmentName — the name of the file to be attached.
◦ mimeType — the type of mime. For example, the mimeType for Testfile.pdf will be application/pdf.
11. Click Execute. This will send an email with the file that you have attached.
12. Click SendMessageWithAttachments and then enter the following details:
◦ from — the valid email address of the sender (for example, as donotreply@domain.com)
◦ to — valid email address specifying the recipient of the email.
◦ cc — valid email address specifying any other recipient to whom the email should be copied.
◦ bcc — valid email address specifying any other recipient to whom the email should be copied and without being visible to other recipients.
◦ subject — the subject of the email.
◦ body — the content of the email (this is an XML parameter).
◦ attachments — the infotable field that you have to select to add multiple attachments. Click attachments and a new page appears as given below.
◦ Add — Click this to add an attachment.
◦ fileRepository — the repository in which the email attachments are stored.
◦ path — the path of file to be attached.
| | If you have stored the attachment in ThingworxStorage/repository/FileRepository, you can directly give the name of file in this field. For example, if the file name is Testfile.pdf, then you can enter this name as it is in this field. |
◦ attachmentName — the name of file to be attached.
◦ mimeType — the type of mime. For example, the mimeType for Testfile.pdf will be application/pdf.
◦ Save — Click this and your attachment will be saved.
| | You can add multiple attachments using Add. Make sure you save all attachments and then you can see those listed in the info table. |
13. Click Execute. This will send an email with multiple attachments.
14. Click SendMessageWithImage.and then enter the following details:
| | Use this service only when you want to attach a single image with the email. Use SendMessageWithImages when you want to attach more than one image. |
◦ from — the valid email address of the sender (for example, as donotreply@domain.com)
◦ to — valid email address specifying the recipient of the email.
◦ cc — valid email address specifying any other recipient to whom the email should be copied.
◦ bcc — valid email address specifying any other recipient to whom the email should be copied and without being visible to other recipients.
◦ subject — the subject of the email.
◦ body — the content of the email (this is an XML parameter).
◦ Image — Click change. This will allow you to browse and select the image that you want to send with the email.
◦ attachmentName — the name of image to be attached.
◦ mimeType — the type of mime. For example, the mimeType for Testimage.png will be image/png.
15. Click Execute. This will send an email with image.
16. Click SendMessageWithImages and then enter the following details:
◦ from — the valid email address of the sender (for example, as donotreply@domain.com)
◦ to — valid email address specifying the recipient of the email.
◦ cc — valid email address specifying any other recipient to whom the email should be copied.
◦ bcc — valid email address specifying any other recipient to whom the email should be copied and without being visible to other recipients.
◦ subject — the subject of the email.
◦ body — the content of the email (this is an XML parameter).
◦ attachments — the infotable field that you have to select to add multiple images. Click attachments and a new page appears as given below.
◦ Add — Click this to add an image.
◦ file — Click change. This will allow you to browse and select the image that you want to send with the email.
◦ attachmentName — the name of the image to be attached.
◦ mimeType — the type of mime. For example, the mimeType for Testimage.png will be image/png.
◦ Save — Click this and your image will be saved.
| | You can add multiple images using Add. Make sure you save all images and then you can see those listed in the infotable. |
17. Click Execute. This will send an email with multiple images.
Click Monitoring > Logs > SecurityLog and you can find the details of any email that was not delivered.