Email Providers
A complete guide to setting up your mailing service
This section of the documentation will help you integrate email providers to your platform.
Adding a new email provider
To add a new email provider navigate to the Integrations section and then to Email Providers.
In order to add a new email provider to your platform, click Add New and select the email provider on the pop-up window. At this time, Tonos offers integration with SmartEmailing, an email tool that makes it easier for you to communicate with customers. If not used, all emails will default to Tonos’ internal email hosting service.
Upon selection you will be navigated to the configuration page. In this page you will be required to add a name to your integration, input the API Key and the SmartEmailing User Authentication credentials (an email address) that is provided from the SmartEmailing account in order to establish the connection between Tonos and SmartEmailing.
The From and ReplyTo parameters are replaced by the organization email address added under Organization Details whereas the Sender Name is replaced with the name of the application for which the configuration is completed.
Configuring the email templates
Parameters determine the type of information that will be replaced when sending emails to users via SmartEmailing. For example, a parameter usersgivenname can be used to replace a user’s First Name on all emails.
Please note that when configuring a template on SmartEmailing you must use the replace notation before every parameter for it to take effect. For example, to replace a user’s First Name, you must use {{replace_usersgivenname}} in the template you configure in SmartEmailing. The replacement must be typed in lowercase letters. The given name will still appear as the user has entered during signup, i.e. if uppercase is used, an uppercase is shown. The same applies to all other parameters.
Please note that bolding the replaced text will cause the connection to break and the parameter will not be replaced.
The Default Parameters are parameters that repeat in multiple emails sent to users. It is not required to use all these parameters. In addition, each email will have its own parameters. Use these parameters for each template of choice at your discretion. Copy them by clicking on each one individually.
Below you will find all the emails Tonos sends to end-users during their various interactions with their identities along with their descriptions. Please note that at this time it is not possible to turn off individual emails. You must configure all templates beforehand otherwise the email integration with SmartEmailing will not function properly and Tonos will default back to its internal email service.
Filling out the email provider form
SmartEmailing
Before creating your email provider, make sure to create an API Key on your SmartEmailing account.
Before activating your campaigns that contain the application that uses the email provider you will create, make sure to setup the new sender email and confirm it on your SmartEmailing account at https://app.smartemailing.cz/userinfo/senders/. Also, make sure to order the DNS settings (which usually takes up to five working days) at https://www.smartemailing.cz/sluzby/nastaveni-domeny/ on your SmartEmailing account, as the emails will be sent to the receivers in their spam folder due to security reasons. For more information, contact SmartEmailing support.
| SmartEmailing | Field | Description |
|---|---|
| Name | This field requires you to write the name of your email provider. |
| SmartEmailing Account API Key | This field requires you to write the SmartEmailing Account API Key which you should have beforehand. |
| SmartEmailing User Authentication | This field requires you to write the SmartEmailing user credentials. |
After submitting the form, Tonos will use the provided credentials to create all the email templates available on your SmartEmailing account and it maps their IDs with Tonos IDs.
After creating the email provider, you will be able to view and edit the IDs of the email templates created when you set up the email provider.
| Description | |
|---|---|
| New Subscription Email | This email is sent to the user when they purchase a subscription. It contains information on their new subscription such as the access granted and how they are able to access their subscription. |
| Cancel Subscription Email | This email is sent to the user when a subscription is canceled either by the user themself or a Tonos administrator. |
| Customer Purchase Subscription | This email is sent to users whenever a subscription is created for them by the administrator. It contains information on their subscription as well as a link that when clicked opens a session for the user in GoPay for them to complete the payment. |
| Grant Access | This email is sent to users whenever a Tonos administrator grants the user access via the Tonos Admin. It contains information that they have been granted access to premium content. |
| Trial Will End Subscription | This email is sent to users when their trial period is about to expire. It informs the user that on the date when the trial expires they will be charged a certain amount to continue their subscription. The email is sent 7 days prior to the first payment unless the trial period is shorter in which case it resorts back to the 1 day prior to the first payment default. |
| Refund Payment Email | This email is sent to users whenever a refund for their order is completed and processed. This informs the customer on the refund process. In addition, a refund receipt is attached to this email. |
| Failed Email Template | This email is sent to users whenever their payment is unsuccessful. Users are invited to review their billing information and attempt to complete the payment again before they are given access to the premium content. |
| Payment Receipt Email | This email is sent when a successful payment is completed upon subscribing. It contains information on their payment including Amount Charged, Date of payment, and Payment Method. |
| User Invitation Email | This email is sent when a Tonos administrator sends an email to users they would like to invite a member to access the Tonos admin. This is not an email sent to end-users. |
| License: Invitation Email | This email is sent to the user when a Tonos administrator or license representative adds the user’s email address to the license. The email contains a message notifying the user they have been granted access to a License via their Organization and a link via which they will be able to redeem their access. |
| Access Expired Email | This email is sent to the end-user when their access has concluded due to the license expiring. |
| License: Access Redeemed Email | This email is sent to the end-user when they successfully redeem their access via the license. |
| License: Access Revoked Email | This email is sent to the end-user when their access has been revoked either by the license representative or by an administrator via the Tonos Dashboard. |
| License: Invitation Revoked Email | This email is sent to the end-user when their invitation to join a license via their organization has been revoked provided that the user has not already redeemed their access. |
| Field | Description |
|---|---|
| Coming soon! | Coming soon! |
| Gjirafa | Field | Description |
|---|---|
| Coming soon! | Coming soon! |
SmartEmailing API Integration
Tonos offers the option to create contact lists on SmartEmailing via API in order to support your communication with the various groups of customers and subscribers. To configure the connection between Tonos and SmartEmailing navigate to ‘Integrations’ and ‘Email Providers’. After having configured an integration with SmartEmailing, in the list view of the configurations, one will see the ‘Configure Settings’ option. Navigating to this option will redirect the user to the Mailing List Settings where one can configure which customer groups are mapped with which SmartEmailing contact list (denoted via ID).
On ‘Add’ one will be able to define the mapping between customer groups and SmartEmailing ID. To configure the integration one must select:
- ‘Customer Group’ which has previously been created under ‘Customers’ that is to be mapped to the SmartEmailing Contact List. Please note that this is a required field.
- ‘Contact List Name’ which denotes the name of the contact list on SmartEmailing. Please note that this is a required field.
- ‘Sender’s Email Address’ which is the business email address used on SmartEmailing and reflects the “From” part of an email creation so that the recipient can identify the sender of the email.
- ‘SmartEmailing ID’ which is the identifier of the contact list on SmartEmailing.
On ‘Create’ the mapping will be added and the SmartEmailing contact list will be automatically updated via the API whenever customers become part of a customer group. One will also have the option to edit or delete a mapping of customer groups and SmartEmailing IDs by right clicking an existing mapping. On ‘Delete’ the syncing between the customer groups in Tonos and the contact list on SmartEmailing is halted. On the list of configurations one can view the date and time when the list was last updated.
Please note:
- Customer Groups are updated every ‘12’ hours. However, they can also be updated on demand by right clicking under ‘Actions’ and clicking ‘Sync’.
- Please note that the sync may take a few minutes to be executed in its entirety. When the sync is completed, the ‘Last Updated’ datetime will be updated as well to reflect the latest sync.
User Groups
User groups are created and managed through user states.
A user state is the current status of the user with a specific product, so a state is always connected to a product. A user can be in only one specific state at a time. The states are switched as soon as a timely update is made or a specific user does an event (subscribe or cancel a subscription).
User states currently available in Tonos are: Registered, Subscribed, Renewing, Canceling, Expiring, Canceled, Expired, InActive.
Keep in mind all states are defined as is, but some of them are configurable through settings.
| User State | Description |
|---|---|
| Registered | A user is in this state if he is part of Tonos users but it didn't have any connection with the specific product. (i.e. subscribed to another product, subscribed to a newsletter) |
| Subscribed | This state defines a user that is subscribed to the product! This user should be subscribed to that product but it isn't still in the renewing, canceling or expiring state. (renewing, canceling and expiring are in the subscription interval but are different states) |
| Renewing | User will be on the state of renewing 7 days before renew subscription time, this setting is specifically for recurring subscriptions The days when to add a user on renewing list can be configured directly on the admin. |
| Canceling | User will be in the state of canceling from the time that user cancels a recurring subscription until the day that his subscription ends and therefore is canceled. |
| Expiring | User will be in the state of expiring 7 days before the end of fixed subscription time. The days when to add a user on an expiring list can be configured directly on the admin. The expiring state is only for fixed-subscribed users. |
| Canceled | User will be in the state of canceled from the day that subscription cancel time is reached, user will stay canceled until inactivity day limit is reached to go to Inactive state. |
| Expired | User will be in the state of expired from the day that subscription expires and wasn't renewed, user will stay expired until inactivity day limit is reached to go to Inactive. |
| Inactive | This state is specified as 30 days after subscription was canceled or expired, and will stay like this until it is resubscribed to the specific product. The days when to add a user on an inactive list can be configured directly on the admin. |
Timing of the states can be set under the Customer Groups Settings property that you can specify timing for these states: Renewing, Expiring and Inactive.