Sending custom emails

Custom Email Notifications

Toqio offers a range of default email notifications designed for specific use cases. While these templates provide a simple and effective way to communicate with users, you may prefer to use your own customised email templates to align with your brand or address unique requirements.
In such cases, you have the option to disable our default email notifications and send your own custom emails using the Custom Email API.

This documentation article will guide you through the process of implementing and managing your own email templates using this powerful tool.

You can find the list of the Toqio email types here.

Setting up Custom emails

To be able to send custom emails, you need to ensure the following:

Email Service Integration

You must have an email service integration set up and authorised with an API key.
If you're already using an existing Connector, you won't need to set up a new API key, as it will be preconfigured with the authorised connection to Toqio.

However, if you decide to set up the service in a new environment, our delivery team can assist you with the API key setup process.

API Key and URL Setup (for new integrations)

Provide us with the URL per environment where Toqio can send requests to your email service integration.
Our delivery team will issue an API key for you, which will be sent in the 'x-api-key' header. This key will enable you to validate that the request originates from Toqio and should be discarded if it does not match.

Access Public API(for new integrations)

Once our delivery team confirms completion on our end, you will gain access to our Public API. This allows you to configure the sender integration based on the specified email types, giving you full control over your custom email notifications.

Before you begin sending your custom emails, it's crucial to disable the corresponding Toqio default emails that you wish to replace.

Disabling Toqio default emails which you would like to substitute

After you disable Toqio the default emails you intend to replace, Toqio will stop sending those particular emails. This lets your custom emails take over without any problems.
Toqio will also tell you when to send your custom emails and give you the variables you need for each email type.
Toqio default emails can be disabled/ enabled individually by using Email Configuration endpoints.
It allows management of email configurations for custom notifications within the email service integration. It supports CRUD operations - to create, read, updated and delete the email configuration

Parameters:
customerId (required): The ID of the customer the configuration is applied for
emailType: The type of email you need to enable / disable. You can find the list of the Toqio email types here.

Responses
The successful response (HTTP status code 200) returns an array of EmailConfigurationDTO objects.
Additionally, the endpoint handles the following error cases:
Invalid URL: Returns HTTP status code 400 if the provided URL is incorrect.
Email Configuration Not Found: Returns HTTP status code 404 if the requested email configuration doesn't exist.
Validation Exception: Returns HTTP status code 422 if there's a validation error in the request.

Implement the logic to process the email related information received from Toqio

When Toqio sends a notification to your email integration, it will include the necessary information for a particular email type. Toqio makes it easy for you to create custom emails by giving you the needed variables for each email type.

To process the email-related information received from Toqio, you need to set up the logic in your email integration.
Utilise the email sending endpoint to send custom emails using the processed information from Toqio.

Handling localisation

You can send emails to your users in different languages. The language can be defined depending on the user’s localisation settings. Toqio will pass the user' localisation to you, so that you can implement the logic to send an email using the relevant to the user language copy.

In the object “variables” you will receive a key-value that can be:
locale: es-ES
locale: en-GB
locale: zh-HK

Set up an email sender system of your choice to send your custom emails

To send your custom emails to users, you'll need to set up an email sender system. This can be done using various options, such as choosing an existing email service provider like SendGrid or creating your own email sending service. Popular email service providers like SendGrid, Mailchimp, or Amazon SES offer tools and services to help you send, track, and manage your custom emails. Feel free to choose the one that best suits your needs and budget.

Example using SendGrid email sender

For the SendGrid set up in your email service integration you can use the sendEmail method which is responsible for preparing and sending custom emails using the SendGrid API.

Here's a step-by-step breakdown of the method.

SendGrid account and API key configuration

To configure SendGrid you can consult this documentation.

After creating a SendGrid account make sure you verify the email address and go through the Domain authentication process.
Before going to the next step, create a SendGrid API key, as it will be used to authenticate your requests.

Java configuration

Add SendGrid to your maven project:

<dependency>
<groupId>com.sendgrid</groupId>
	<artifactId>sendgrid-java</artifactId>
	<version>4.7.1</version>
	</dependency>

Import the necessary libraries from SendGrid in your class.

Add the just created API key to your project, as an environment variable or as a class variable.

Sending an email

For the SendGrid set up in your email service integration you can create a method which is responsible for preparing and sending custom emails using the SendGrid API.

Here's a step-by-step breakdown of the steps needed to send an email:

Initialise Email Components: Start by creating Email objects for the sender and receiver, and a Mail object to store the email details.
Set Subject: Set the subject line of the email.
Add Personalisation: Create a Personalisation object and add the receiver's email address to it. This ensures that the email is tailored to the recipient.
Set Template ID: Based on the emailType, assign the corresponding SendGrid template ID. This enables the method to populate the email with the appropriate content and layout.
Add Dynamic Template Data: Populate the email template with dynamic data using the variables provided in the EmailNotificationContentDTO. This allows you to customise the email content according to your needs.
Add Attachments: If there are any attachments to be sent along with the email, add them to the email object.
Send Email: Finally, create an instance of the SendGrid class and use the SendGrid API to send the prepared email to the recipient.

As a note, the variables sent in the request will vary depending on the EMAIL_TYPE field, and thus the template used. Due to this, the method will need to implement the logic to decide which templateId will be used and the variables sent in the email. If you want to add any new variable (created by you, not sent in the request by TOQIO) this will be the place to add them.

Example code:

public void sendEmail(EmailNotificationContentDTO emailNotificationContent, String emailType){  
   Email from = new Email("[[email protected]](mailto:[email protected])");  
   String subject = emailNotificationContent.getSubject();  
   Email receiver = new Email(emailNotificationContent.getReceiver());  
   Mail mail = new Mail();  
   mail.setFrom(from);  
   mail.setSubject(subject);  
   Personalization personalization = new Personalization();  
   personalization.addTo(receiver);  
   //We'll use the adequate templateId and variables for each emailType  
   if (emailType.equals("INVITE_USER")){  
       mail.setTemplateId("d-dd1301d4aa554adaa3de0ad87c652484");  
       personalization.addDynamicTemplateData("linkUrl", emailNotificationContent.getVariables().get("linkUrl"));  
       personalization.addDynamicTemplateData("companyName", emailNotificationContent.getVariables().get("companyName"));  
   }  
   mail.addPersonalization(personalization);  
   // Add attachments if there is any  
   if (!CollectionUtils.isEmpty(emailNotificationContent.getAttachments())) {  
       emailNotificationContent.getAttachments().forEach(attachment ->  
           mail.addAttachments(attachment.toSendGridAttachment())  
       );  
   }  
   SendGrid sg = new SendGrid(sendGridApiKey);  
   Request sgRequest = new Request();  
   try {  
       sgRequest.setMethod(Method.POST);  
       sgRequest.setEndpoint("mail/send");  
       sgRequest.setBody(mail.build());  
       sg.api(sgRequest);  
       log.info("Email sent successfully.");  
   } catch (IOException ex) {  
       log.error("Error sending email: {}", ex.getMessage());  
   }  
}

In the example above, the method sendEmail is called after processing the request from TOQIO to the connector. In the request to the endpoint “/notifications/email/send”, an EmailNotificationRequest object will be sent.

This contains an emailType, the customerId, and a list of email contents of the same type. We have to call sendEmail method once for each email, and send the emailType as an argument:

emailNotificationRequest.getNotifications().forEach(n ->  
   {  
       log.info("Sending email");  
       sendEmail(n, emailNotificationRequest.getType());  
   }  
);