First, please add the connection parameters for your access to the Neoletter API to the server properties file, conf/server.properties:
psa.neoletter.url= URL of the Neoletter API, including the account IDpsa.neoletter.aut.url= URL of the authentication service (IAM)psa.neoletter.aut.id= Client IDpsa.neoletter.aut.sec= Client secretpsa.neoletter.snd.ema= overwrites the sender address of the serial email in the CRM
All sender email addresses must be registered with and confirmed by Amazon Simple Email Services (SES) prior to first use. For this, please contact our support team, which will be happy to assist you with the registration process.
Alternatively, you can do without specifying a sender address if psa.neoletter.snd.ema is initialized with $NONE. The sender can then be selected in the Neoletter user interface, which ensures that only registered sender addresses are used.
psa.neoletter.url=https://api.justrelate.com/neoletter/instances/<Tenant-ID>
psa.neoletter.aut.url=https://iam.justrelate.com/token
psa.neoletter.aut.id=
psa.neoletter.aut.sec=
psa.neoletter.snd.ema=
Alternatively, with JustRelate CRM, the access credentials can be configured by means of environment variables. Their advantage is that they can be created on a per-user basis, which can be useful, in particular with respect to the sender address. The naming scheme uses the same names, however, in upper case letters, and with underscores ("_") instead of dots.
psa.neoletter.url = PSA_NEOLETTER_URLpsa.neoletter.aut.url = PSA_NEOLETTER_AUT_URLpsa.neoletter.aut.id = PSA_NEOLETTER_AUT_IDpsa.neoletter.aut.sec = PSA_NEOLETTER_AUT_SECpsa.neoletter.snd.ema = PSA_NEOLETTER_SND_EMA
To create the data for authenticating at the Neoletter API, please open the JustRelate Console for your Neoletter account, and proceed as follows:
The client ID and secret are displayed in a separate popup window and can now be transferred to the configuration. Please note that the client secret is displayed only once on creation of the API key. Further details about API keys can be found in the JustRelate Console documentation.
Each API key belongs to exactly one user within a JustRelate account. All requests to the Neoletter API are performed with this user’s permissions.
CRM users who want to work with mailings in Neoletter require a personal JustRelate login. To obtain such a login, please contact our support, which will then send you an invitation email via the JustRelate Console. This email will contain a link to the login page, where you can either sign up, or log in via a third-party service such as Google or Facebook. You will be granted the permissions needed for working with Neoletter by our support team as well, which will assign you to a team for this.
The interface between the CRM and Neoletter is implemented in a *.jar file. Further or other external mailing systems can be integrated as well, and then controlled via an interface.
The list in the Administration/Activities/Correspondences/External email system menu presents the interfaces of the email systems, including their respective identifier. By default, the Neoletter implementation is selected here. Should this not be the case, the Set default function lets you activate the Neoletter interface.
The mailing system to use (select) can also be specified by means of the PSA_EXT_EMA_ITF variable by setting it to the corresponding interface identifier from the above-mentioned list (PSA_EXT_EMA_SYS_NEO_LET for Neoletter).
From within the CRM, you can reference a Neoletter mailing template. When exporting a serial email to the external mailing system, the new mailing and the existing template will be linked together. This makes it possible to reuse attractive and email-client-optimized mailings created with Neoletter in the CRM.
There is a function available for conveniently creating a Neoletter template for any serial email that has not been sent yet:
For serial email templates to be selectable in a structured manner, the templates are stored in the Global templates/Neoletter scope as a default. You can adjust the template scope structure of your own templates via the CRM template management. The templates created in this way can be selected when creating a serial email in the CRM.
When a serial email is transmitted to Neoletter, the recipient list with all its contacts is passed to the mailing concerned. In this list, initially only the email field is required, however, often additional fields are used in order to, for example, personalize emails after those fields have been linked to the corresponding data in the CRM. Neoletter supports several basic fields that the interface links automatically. If you additionally wish to access other pieces of information from the CRM in your mailings, a mapping between the internal and external fields is needed. Such a mapping is global, meaning that it applies to all users and serial emails alike.
| Field name (JustRelate CRM) | Internal name (JustRelate CRM) | Field (Neoletter) |
|---|---|---|
| Salutation | PSA_CON.SEX_NAM | gender |
| First name | PSA_CON.FST_NAM | given_name |
| Last name | PSA_CON.NAM | family_name |
| Composed name | PSA_CON.CMP_NAM | name |
| Form of address | CPD_FOA | salutation |
| Phone number (business) | PSA_CON.TEL_COM | phone_number |
| Organization | PSA_ORG.CMP_NAM | company |
EMA_ADR |
In Neoletter, the email address also represents the recipient’s key field.
For Neoletter to successfully send emails, each recipient must have given their consent to receiving emails. When exporting the recipient contacts, the interface assumes that only contacts who consented are used, and automatically sets “consent” to “given”.
You can open the mapping list via the Administration/Correspondences/External email system: Field mapping menu. In the standard, this list is empty and needs to be maintained as needed. For this, knowledge of the CRM data model is required!
Examples of global field mappings
The Name column provides general field designations.
The technical name of a CRM field can be entered in the CRM field column. The basis of all fields is the contact list of the serial email (PSA_CON_CPD_AGG) whose attributes (including the contact component) can be accessed directly. In one of the examples above, PSA_CON.CMP_NAM causes the name from the contact’s “Name” component field to be written to the “name” External field of the recipient list in Neoletter.
The External field column defines the name of the field in Neoletter. Note that the above fields are basic fields and as such don’t need to be mapped. All the fields defined in the mapping list are created in Neoletter as custom fields, and the corresponding placeholders are given a prefix, custom_, so in the above “name” example, this field becomes the “Custom name” field in Neoletter with its custom_name placeholder.
The Import field column lets you select the target field (selector) when importing contacts. This option is not used since the Neoletter API does not support importing contacts.
Some of the attributes of the recipients in the contact list of the serial email may not be accessible because they are protected in the contact component, and thus invisible. The special character “@” causes the contact to be opened again without protection.
Example:PSA_CON.NAM@PSA_CON
In the standard, the NAM („name“) field is protected and cannot be retrieved from the recipient list. By adding @PSA_CON, the key value (FAT_GID) of the contact’s relationship is read, the PSA_CON data object opened, the FAT_GID looked up in the primary key value (PSC_GID) from which the name (PSA_CON.NAM) is then read. In this way, you can access protected fields.
The @ character reopens the contact in a special data object (DTO), in which you can find and retrieve the required field.
You can check whether the fields are properly mapped by marking the corresponding rows in the mapping list and executing the Check attributes function. This function checks if the identifiers provided in the “CRM” column can be queried without causing an error. External field identifiers are not checked because they are not subject to restrictions in Neoletter, so it is recommended that you carefully check their spelling, as Neoletter does not validate placeholders.
Sometimes, there may be attributes in the external mailing system that are not directly available in the recipient list of the serial email because they are not contained in the contact component. The extended notation in the “CRM” field allows you to search for a different data object based on the PSA_CON_CPD_AGG base class. For this, you can specify a field of the base class from which the search condition is determined. Furthermore, the data object and field to be searched is specified, as well as the field that finally returns the result.
Example 1:PSA_PRO.NAM@PSA_CPD_XRO.PSC_GID=CHD_GID
We require the keyword of the main project of the serial email, which is not included in the recipient list. For this, the key value CHD_GID is read from PSA_CON_CPD_AGG and searched for in PSC_GID of PSA_CPD_XRO. From the identified activity, the value of the PSA_PRO.NAM field is then returned.
Example 2:PSA_CRE_PRS.CMP_NAM@PSA_CON_XTD.PSC_GID=FAT_GID
We are looking for the name of the recipient’s account manager. First, the FAT_GID key value is determined from the source object and searched for in the PSC_GID field of the object PSA_CON_XTD. The contact found delivers the value in the PSA_CRE_PRS.CMP_NAM field.
Example 3:PSA_CTY.NAM@PSA_ADR_XTD.CON_GID=FAT_GID
We require the country from the recipient’s address. For this, the original object, PSA_CON_CPD_AGG, returns the FAT_GID key value that is searched for in the CON_GID field of the PSA_ADR_XTD data object. The country being looked for can now be taken from the PSA_CTY.NAM field.
For better readability of the field mapping, we recommend to exclusively use the extended notation. The PSA_CON.NAM@PSA_CON example given above becomes PSA_CON.NAM@PSA_CON.PSC_GID=FAT_GID in the extended notation.
For defining the field mapping, precise knowledge of the internal field names in the CRM is needed. To determine these names, the Show field information function, for example, is available.
With JustRelate CRM, several email addresses can be assigned to each contact, in any order. By means of the PSA_CON_EMA_FLD_SEL setting, you can change the search order by means of which the email address for the recipient list or serial email is selected. The first of the specified addresses is used. This setting additionally defines the order of the addresses for selection in the email field. When the addresses used in the serial email are passed to the external mailing system, they are also used as the key of the respective recipients. For this reason, the PSA_CON_EMA_FLD_SEL setting also affects the interface to Neoletter.
This setting also affects the groupware synchronization behavior.
The response data of the mailings sent can be imported into the CRM system either by clicking a button or automatically by means of the Update mail response job (PSA_EXT_EMA_RSP). For controlling this import function, the following parameters are available:
CLS_DAT:= Search condition for Sent on (e.g. >=$TIME-1M | '')EXT_ADD_KEY:= Search condition for External key 2 [optional]SET_CTT:= Generate preview (Y|N)In addition, you can use the Mailing list registration synchronization job (PSA_EXT_EMA_LIS_SYN) to synchronize unsubscribes of recipients with the contact data in the CRM system. The job imports response events regularly from Neoletter and checks if any subscription cancellations have been registered. If this is the case, an email series lock is automatically applied to the identified contacts.
The job parameters are not relevant for use with Neoletter as an external mail system, because automatic import of contacts is not supported. Please leave the parameter field empty to start the job with its default settings.
In the standard, these jobs are configured for being executed once per day. You can find the job management in the Administration/Tools/Jobs menu.