Configure the application Simply SMTP with OAuth 2.0 authentication and use magnews as the outbound mail server for sending transactional email messages.
Authentication with OAuth 2.0
Premise: the parameters and configurations suggested on this page may not be suitable for specific situations or Magnews On premise installations. Before proceeding, we recommend checking with our Help Desk to ensure the instructions provided are appropriate for your infrastructure.
For security reasons, we use a monitoring service for the expiration of platform user passwords.
If the password for the user you created to manage the Simple Mail Transfer Protocol (SMTP) services expires, the service will stop functioning.
To reactivate the service, you will need to create a new password and update it in the applications that use that service.
Therefore, we suggest using a solution that avoids the need to update the password by implementing the OAuth 2.0 protocol (https://oauth.net/2/).
This solution guarantees - along with the use of tokens generated by Magnews - a more secure authentication system with the added benefit of ensuring individual access privileges and the ability to revoke them without inhibiting user access to services.
The first step to implement this procedure is to create a digital certificate for your application.
The certificate is essential to request an access token and a refresh token, which allow your application to automatically renew expiring tokens.
Create a digital certificate
Access the Settings menu and then to the Web service > Digital certificates section
Create a new certificate and, for the Type of certificate field, choose the option OAuth 2.0 Client Application
In the Name field, enter the label of the certificate (it is only for identification in magnews).
Enter the information regarding:
- Application ID: necessary for the client_id parameter
- Display Name: shown to the user in the authorization request form
- App Secret: required only in some cases (e.g., for JS-only clients); it can be modified and is not displayed for security reasons
- OAuth redirect URI: required only if the certificate is used by a web application
Utility functions
After creating the certificate, the Utility functions section appears on the same page with information on:
- Token location URL: address to transform the provided parameters into an access token or to use a refresh token
- Token information: descriptive link about the token
- Receive access token: button that allows you to immediately obtain an OAuth 2.0 access token
- REST API Explorer: to perform REST API tests on magnews
Get an access token
Once the digital certificate is created, you can obtain an immediate access token.
Click on Receive access token to view all information about the token.
You can modify the token's duration (default set to four hours) or immediately revoke its validity (button Revoke access).
Client and token length
Some clients have a password length field shorter than the number of characters that make up the tokens.
In this case, there is a risk that the client will respond that the login credentials are incorrect. If you encounter this issue, contact our Help Desk, who will assist you in resolving it.
Important: the SMTP client you use must be configured to use connections through the secure channel STARTTLS. If this connection method is not adopted, authentication attempts will fail and the integration with the Simply SMTP solution will not work.
Configuration and use of Simply SMTP
Creating a dedicated user
The first step to configuring Simply SMTP is creating a user dedicated to this service.
To create the user, access the Settings menu and then the Users and security > Users section. Click on New User and proceed with the configuration.
Copy and keep safe the username (also called user ID) and the password of the created user, as you will need them later for the configuration of Simply SMTP.
Important: after creating the user, contact our Help Desk to activate the sending permission, necessary for sending messages with Simply SMTP.
Creazione di una categoria transazionale
The second step is the creation of a transactional category, within which a dedicated message type will be created for sending via Simply SMTP.
The message type is useful for identifying, in the Insight section, the reports dedicated to transactional emails sent with Simply SMTP.
To access the category management page, follow the menu Journey Lab > Settings > Transactional categories.
Click on New category, assign a Name and click Create Category
Creating a message type
Now define the Message Type.
Follow the menu Journey Lab > Settings > Transactional types and click on New Message Type
Select the category, define the Name of the message type, and decide if messages of this type should also be sent to unsubscribed contacts in magnews.
Click on Create Type.
Simply SMTP configuration
To use the Simply SMTP follow the path Settings > Developer > Simply SMTP
and configure the necessary options in the General section:
- Enable Simply SMTP: enable or disable the module functionality
- Track openings and clicks: enable or disable tracking of open and click events for sent messages
- Identify contacts and update their statistics: verify if the message recipient matches a contact in the specified database; the message is associated with the recognized contact and their statistical data is updated
- Database: select the magnews database in which to search for contacts; if the database key is not the email, the contact is associated only if the email is unique
- Subscribe new contacts: message recipients are added as new contacts, with the status subscribed; caution: personal and profiling data of contacts are managed
- Source: associate the origin for each newly inserted contact, to filter contacts and/or define specific dynamic audiences
- Consider the Blacklist for the messages managed by the Simply SMTP: for contacts in the blacklist, the message will not be sent and a bounce will be automatically generated
- Type of transactional message: specify the message type (see section “Creating a message type”) to record and display statistical data
- Journey for tracked links: if a web domain is not indicated (see field below), the domain of the selected journey is used for the links of messages sent by Simply SMTP
- Web domain: web domain associated with the links of messages sent by Simply SMTP
- Add CSS inline styles in HTML emails: you can include inline CSS in your messages, but be cautious: it might result in a slowdown in sending performance
You may need to send different types of messages and want to categorize them for better organization and recognition in statistics.
To this end, as described in the paragraph Creating a message type:
- Access the Message types page
- Create the message types you need
- Next to each message type, you will notice a number; this is the ID of the message type (
idtype
) -
Assign each message its own idtype
Insert the following string in the header of each transactional message:
x-mn-idtype: {my_id}
where {my_id} is the idtype shown in the list of transactional types
The result obtained will be as follows, for example:
In the Credentials section, you'll find all the parameters necessary to configure your external service to interface with the Simply SMTP of magnews:
The Username shown is that of the user with whom you are configuring the Simply SMTP.
When you configure the external service using the Simply SMTP service, enter as Username the one created following the instructions in the paragraph “Creating a dedicated user“, followed by the @ symbol and the client code of your magnews account, for example: helpdesk@magnewsdoc.
In the Password field, enter the access token (see paragraph “Get an Access token“) or the password associated with the user.
Message headers
For transactional messages, you can add some of the following headers:
-
x-mn-idtype: specifies the type of transactional, indicating the ID; e.g.
x-mn-idtype: {my_id_type}
-
x-mn-cssinline: if you activate the option Include inline CSS styles in HTML emails, it includes inline CSS styles, e.g.
x-mn-cssinline: true
-
x-mn-iddb: if you activate the option Subscribe new contacts, you can specify the database ID to which the contacts should be added; e.g.
x-mn-iddb: 1
-
x-mn-webdomain: specifies a web domain for the tracked links in the message; e.g.
x-mn-webdomain: {Web_domain_name}
-
x-mn-externalid: assigns an external ID (string) to the message, used to identify the message from apps or in other operations; e.g.
x-mn-externalid: {external_id}
-
x-mn-idpolicy: specifies the ID of a delivery policy to be used for sending the message; e.g.
x-mn-idpolicy: 4
-
x-mn-donotcreatesimplemessage: if you set true the message is created and pre-send checks are performed, but the message is not actually sent; e.g.
x-mn-donotcreatesimplemessage: true