JobRequest method
Requirements
The request will accept only HTTP-method POST and Content-type="application/json". The caller must ensure the charset of the JSON in the body-content to be UTF-8.
Definition of “Key: Value”: an element must exist with non-empty content (not allowed: key: NULL, key: “”).
REST Method
This method allows you to create an email job.
Legend: (m) for mandatory; (o) for optional.
Subject (m)
Elements (m/o) | Default | Description |
contentEncoding (o) | plain | Encoding provided in caller's request. Allowed values: plain, quoted-printable, base64 Content examples: plain: 'testööäüü' quoted-printable: '=?UTF-8?Q?test=C3=B6=C3=B6=C3=A4=C3=BC=C3=BC?=' base64: 'dGVzdMO2w7bDpMO8w7w=' |
contentTransferEncoding (o) | as results by applying javax.mail mechanism to subject.content | Encoding of rendered MIME Allowed values: base64 |
charset (o) | UTF-8 | All standard charsets supported by Java 8, e.g.: "US-ASCII", "ISO-8859-1", "UTF-8", "UTF-16", "UTF-16LE" and "UTF-16BE". |
content (m) | - | Subject will be "folded" every 78-chars by "<newline><blank>", as described in https://tools.ietf.org/html/rfc5322#section-2.1.1. Max. 500 chars |
features (o) |
|
|
template (o) |
- | Clarification for using Freemarker Template in subject Only base64 characters are allowed
Content examples: |
body (o)
Elements (m/o) | Default | Description |
contentType (m, if parent element exists) | - | Allowed values. text/plain, text/html If value = text/plain and an alternative is present, the alternative will not be generated into MIME-message. |
contentEncoding (o) | plain | Encoding provided in caller's request. Allowed values: plain, quoted-printable, base64. |
contentTransferEncoding (o) | as results by applying javax.mail mechanism to body.content | Encoding of rendered MIME Allowed values: base64 |
charset (o) | UTF-8 | All standard charsets supported by Java 8, e.g.: "US-ASCII", "ISO-8859-1", "UTF-8", "UTF-16", "UTF-16LE" and "UTF-16BE". |
content (m, if parent element exists)) | - | For any feature that requires to parse of the HTML content (like open tracking), a valid HTML, incl. JSON-LD, content with <html> & <body> tags is mandatory. |
template (o) | - | Clarification for using Freemarker Template in subject. Only base64 characters are allowed. Content examples: |
alternative (o)
Elements (m/o) | Default | Description |
contentEncoding (o) | plain | Encoding provided in caller's request. Allowed values: plain, quoted-printable, base64 |
contentTransferEncoding (o) | as results by applying javax.mail mechanism to alternative.content | Encoding of rendered MIME Allowed values: base64 |
charset (o) | UTF-8 | All standard charsets supported by Java 8, e.g.: "US-ASCII", "ISO-8859-1", "UTF-8", "UTF-16", "UTF-16LE" and "UTF-16BE". |
content (m, if parent element exists) | - | If present, always considered as contentType = text/plain |
template (o) | - | Clarification for using Freemarker Template in subject Only base64 characters are allowed Content examples: |
attachments (o)
Elements (m/o) | Default | Description |
attachment <array> (o) | - | Max. 20 "attachment"-subelements |
attachment
Elements (m/o) | Default | Description |
name (m, if parent element exists) | - | Attachment file name, max. 250 chars. Note: Unsupported attachment file extensions are listed in a chapter below. |
contentType (m, if parent element exists) | - | Max. 100 chars; only ASCII. Allowed format: "<major>/<minor>" e.g. application/pdf <major> and <minor> min. length = 1 |
contentId (o) | - | Anchor for references used to embed inline images in html parts. e.g. can used with "contentType": "image/jpeg" max. 100 chars |
content (m, if parent element exists) | - | Content has to be provided always in base64-encoding |
secureDocument (o) |
false | Trigger point for activation for Secure Document Handling. NOTE: Encryption with referenced attachment by Templating Store Manager is not possible |
recipients (m)
Elements (m/o) | Default | Description |
mail <array> (m) | - | for each recipient-subelement in this array, a MIME-message will be built. Min. 1 "recipient"-subelement; |
recipients (m)
Elements (m/o) | Default | Description |
features <array> (o) | - | for each recipient-subelement in this array, features can be activated. |
recipients/features (o)
Elements (m/o) | Default | Description |
openTracking (o) | - | for each recipient-subelement in this array the feature open tracking can be activated. |
recipients/features/openTracking (o)
Elements (m/o) | Default | Description |
active (m, if parent element exists) | false | Enables or disables open tracking for the related recipient. It overwrites the same option eventually set on job level. This feature requires a valid HTML content. Job will be rejected in case of an invalid HTML content. The HTML content must contain both <html> and <body> tags. Allowed values: true, false |
linkTracking (o) | - | for each recipient-subelement in this array the feature link tracking can be activated. |
recipients/features/linkTracking (o)
Elements (m/o) | Default | Description |
active (m, if parent element exists) | false | Enables or disables link tracking for the related recipient. It overwrites the same option eventually set on job level. This feature requires a valid HTML content. Job will be rejected in case of an invalid HTML content. The HTML content must contain both <html> and <body> tags. Allowed values: true, false Restriction: For the usage of Link-Tracking all URLs within the HTML-Code must be shorter than 250 characters. |
templating <array> (o) | - | for each recipient-subelement in this array the feature Templating can be activated. |
recipients/features/templating (o)
Elements (m/o) | Default | Description |
personalization <array> (o) | - | Clarification of Personalization fields for using Templating |
recipients/features/templating/personalization (o)
Elements (m/o) | Default | Description |
<variableName> (m) | - | Map of "custom variables. They must exist for using the templating in your message Min. 1 Max: 15 Request-Sample: "personalization": { "name": "Ignaz", “street”: “Ignaz street” , …., “zip”: “12345” } |
recipients/recipient/mail (m)
Elements (m/o) | Default | Description |
to / email (m) | - | Array of email-subelements, which represents a corresponding receiver email address. For each email subelement a SMTP email will be generated and sent separately - trackable by a corresponding email-ID. Each array entry may contain the friendly name between quotas. In this case the email address has to be delimited by angle brackets. Max. 254 chars per email address. Must contain syntactical correct email addresses. Furthermore, each email address can be checked against the account specific suppression list. Duplicates in this array will be ignored. More information about how to define a recipient’s address can be found in a chapter below! |
Cc / email (o) | - | Carbon Copy - Array of email-subelements, which represents a corresponding receiver email address. For each email subelement a SMTP email will be generated and sent separately - trackable by a corresponding email ID. Each array-entry may contain the friendly name between quotas. In this case the email address has to be delimited by angle brackets. Max. 254 chars per email address. Must contain syntactical correct email addresses. Furthermore, each email address can be checked against the account specific suppression list. Duplicates in this array will be ignored. |
bcc / email (o) | - | Blind Carbon Copy - Array of email-subelements, which represents a corresponding receiver email address. For each email subelement a SMTP email will be generated and sent separately - trackable by a corresponding email ID. Each array-entry may contain the friendly name between quotas. In this case the email address has to be delimited by angle brackets. Max. 254 chars per email address. Must contain syntactical correct email addresses. Furthermore, each email address can be checked against the account specific suppression list. Duplicates in this array will be ignored. |
replyTo / email (o) | Configurable by domain | ReplyTo - If exists, it overwrites the mail/replyTo for the MIME- message which belongs to the containing recipient-subelement. May contain the friendly name between quotas. In this case the email address has to be delimited by angle brackets. Max. 254 chars. Must contain syntactical correct email address. |
inReplyTo (o) | - | If exists, it overwrites the mail/inReplyTo for the Mime-message which belongs to the containing recipient-subelement. |
priority (o) | NORMAL | If exists, it overwrites the mail/priority for the MIME-message which belongs to the containing recipient-subelement. Note: “priority” is not used to prioritize the emails within the sending queue! Allowed values: HIGH, NORMAL, LOW |
listUnsubscribe (o) / (CSA: m) | - | Can be used by caller's systems for their own unsubscribe handling. Highly recommended for marketing emails. Supported by specific major ISPs (like Google Gmail). https://www.ietf.org/rfc/rfc2369.txt By default, when a List-Unsubscribe URL or mailto: is detected, a One- Click-Post Header is automatically added. Either “listHelp” or “listUnsubscribe” must be specified in order to be CSA compliant. |
listHelp (o) / (CSA: m) | - | Can be used to provide an access point for detailed user support information. Recommended for transactional emails, as an alternative to the “listUnsubscribe” header. Supported by specific major ISPs (like Google Gmail). https://www.ietf.org/rfc/rfc2369.txt Either “listHelp” or “listUnsubscribe” must be specified in order to be CSA compliant. |
xHeaders (o) | - | Map of "custom" x-headers. if exists, it overwrites the mail/ xheaders/<headerName> for the MIME message which belongs to the containing recipient-subelement. Header names may not be null, empty or only blanks. Header-values will be "folded" every 78-chars by "<newline><blank>", as described in https://tools.ietf.org/html/rfc5322#section-2.1.1 Header-name has to start with (ignore-case) "X-". Headers with name like (ignore-case) "X-RETARUS-*" or "RETARUS-*" will be ignored. Max. header count = 10 For using Google-FBL you are able to integrate the required Element “FeedbackID” - Feedback-ID: a:b:c:SenderId) Feedback-ID is the name of the Header to be embedded. a, b, c are optional fields that can be used by the sender to embed up to 3 Identifiers (campaign/customer/other). SenderId is a mandatory unique Identifier (5–15 characters) chosen by the sender. It should be consistent across the mail stream. |
recipients/recipient (o)
Elements (m/o) | Default | Description |
reference (o) | - | Offers the possibility to add a reference, which can be processed afterwards in the caller's systems. Max. 50 chars |
mail (m)
Elements (m/o) | Default | Description |
from / email (m) | - | SMTP-from; this property is also the source for validating the registered sender-domain. May contain the friendly name between quotas. In this case the email address has to be delimited by angle brackets. Max. 254 chars. Must contain syntactical correct email address. Has to be a valid entry in list of registered sender addresses for this domain in domain settings. |
mimeFrom / email (o) | mail.from | MIME-from; May contain the friendly name between quotas. In this case the address has to be delimited by angle brackets. Max. 254 chars. Must contain syntactical correct email address. Has to be a valid entry in list of registered sender addresses for this domain in domain settings. |
replyTo / email (o) | Configurable by domain | replyTo-entry which has to be inserted in MIME message May contain the friendly name between quotas. In this case the address has to be delimited by angle brackets. Max. 254 chars. Must contain syntactical correct email address. |
inReplyTo (o) | - | inReplyTo-entry which will be inserted in MIME message. |
priority (o) | NORMAL | priority which has to be set for the MIME message if not provided, the default will be used. Allowed values: HIGH, NORMAL, LOW |
xHeaders (o) | - | Map of "custom" x-headers, which will be set in the MIME message. Header name has to start with “X-“. Header names may not be null, empty or only blanks. Header-values will be "folded" every 78-chars by "<newline><blank>", as described in https://tools.ietf.org/html/rfc5322#section-2.1.1 Headers with name like (ignore-case) "X-RETARUS-*" or "RETARUS- *" will be ignored. Max. header count = 10 For using Google-FBL you are able to integrate the required Element “FeedbackID” - Feedback-ID: a:b:c:SenderId) Feedback-ID is the name of the Header to be embedded. a, b, c are optional fields that can be used by the sender to embed up to 3 Identifiers (campaign/customer/other). SenderId is a mandatory unique Identifier (5–15 characters) chosen by the sender. It should be consistent across the mail stream. |
job (o)
Elements (m/o) | Default | Description |
referenceJob (o) | - | Offers the possibility to add a customer's reference, which can be processed afterwards in the caller's systems. Max. 50 chars |
costCenter (o) | - | Offers the possibility to add a customer's costCenter, which can be processed afterwards in the caller's (billing) systems. Max. 50 chars |
campaignId (o) | - | Offers the possibility to add a customer's campaignId, which can be processed afterwards in the caller's (CRM) systems. Max. 50 chars |
features (o) | - | Definition of feature options |
features/openTracking (o)
Elements (m/o) | Default | Description |
active (m, if parent element exists) | false | Enables open tracking for all recipients. Option can be individually overwritten on recipient level. This feature requires a valid HTML content. Job will be rejected in case of an invalid HTML content. The HTML content must contain both <html> and <body> tags. Allowed values: true, false |
features/linkTracking (o)
Elements (m/o) | Default | Description |
active (m, if parent element exists) | false | Enables link tracking for all recipients. Option can be individually overwritten on recipient level. This feature requires a valid HTML content. Job will be rejected in case of an invalid HTML content. The HTML content must contain both <html> and <body> tags. Allowed values: true, false Restriction: For the usage of Link-Tracking all URLs within the HTML- Code must be shorter than 250 characters. |
features/templating (o)
Elements (m/o) | Default | Description |
active (m, if parent element exists) | false | Enables templating for all recipients Allowed values: true, false |
features/antivirus (o)
Elements (m/o) | Default | Description |
active (m, if parent element exists) | false | Enables antivirus for all recipients Allowed values: true, false |
features/secureDocument (o)
Elements (m/o) | Default | Description |
active (m, if parent element exists) | false | Enables Secure Document Handling for all recipients Allowed values: true, false |
filename (o) | - | always considered as contentType = text/plain |
subjectPrefix (o) | - | always considered as contentType = text/plain e.g. "Password for: <original mail subject - trimmed>" |
password/type (m) | - | For using secure Document, you must have to define which kind of password strength should be use.
|
features/messageSigning (o)
Element m/o) | Default | Description |
active (o) | false | Enables message signing for all recipients. Allowed values: true, false |
notification/endPoint
All content is assumed to be provided with charset = UTF-8.
Elements (m/o) | Default | Description |
url (m, if parent element exists) | - | Denotes the target for sending the notification messages for this job Contains also the protocol for sending the notification messages - initially only HTTP/S supported. Max. 1000 chars |
headers (o) | - | Map of custom headers provided by caller for being propagated into each notification-call. Max. 10000 chars |
notification/endpoint/authentication
Elements (m/o) | Default | Description |
method (m, if parent element exists) | BASIC | Allowed values: BASIC Alternatively, the Authorization header can be defined directly in the header field. |
user (m, if parent element exists) | - | User name for accessing target endPoint described in notification. /url |
password (m, if parent element exists) | - | Password for accessing target endPoint described in notification. /url |
During the Implementation phase, it is also possible to store default values within the configuration for scenarios in which some of the aforementioned variables are not utilized in every REST JobRequest.
Please be aware that all details of the Push Notification service must always be provided in full. For instance, ifyou specify a webservice thatnecessitates authentication witha username and password, these credentials must be explicitly added in the REST JobRequest. In such cases, no default values from configuration will be used. Refer to chapter “7.2 Web-Service” for further details.