E-mail

Overview

The Email service supports two operation modes:

• For outbound emails: the service captures such emails and identifies value placeholders that are used as references of the recipients' sensitive data. Then, it swaps these placeholders with their clear-text values by pulling them from the InCountry Vault. Once sensitive data is replaced, an email with clear-text values is routed to your SMTP server within the same country and this email is further delivered to the target recipient.
• For inbound emails: the service captures emails and redacts their values, such as: sender, subject, and email body. Then saves this sensitive data to the InCountry Vault. After this, Email service delivers redacted emails to your system, so regulated data does not even touch your servers as the email becomes fully depersonalized.

You can manage Email services, as follows:

• create new Email services
• edit the existing Email services
• delete the no longer needed Email services
• view and download logs of the specific Email service

Email Service for Outbound Emails

How It Works

Typically, your application sends an email with regulated data directly to the addressee, violating local data regulations if the application server is located in a country different from the recipient’s country of origin. Email service resides between your application that sends outbound emails and your SMTP server located in the recipient’s country of origin. Your SMTP server must be in the recipient’s country of origin so that no compliance regulations are violated. Email service captures outbound emails with regulated data placeholders, identifies them according to the pre-defined patterns, and then substitutes these placeholders with clear-text values, such as names and email addresses. Once the data is unredacted, it sends emails via a direct SMTP connection to your SMTP server that further delivers this email to target recipients.

This allows to your applications to comply with data residency regulations without modifying the underlying codebase and setting up data stores for regulated data in multiple countries.

In the following diagram, you can see how Email service for outbound emails works. Here also you can see InCountry Border (Web Services) which redacts and stores records data in the InCountry platform. Then these stored records data uses InCountry Email service to unredact the outbound email from your application.

The data flow can be represented in the following way:

Requirements

Email service for outbound emails imposes requirements on emails as follows:

1. Only one addressee is in the To field.
2. The CC and BCC fields are ignored during the email handling.
3. The From and To fields, as well as the email subject and email body, are unredacted if placeholders match the pre-defined patterns, like email1@pk-profile_key006jkdsa00000oLpo.aa.
4. The email’s subject and body can contain placeholders with redacted data that will be replaced with clear-text values upon unredaction like %profile_key=006jkdsa00000oLpo,price%.
5. Emails in the HTML and plain-text formats are supported.
6. Attachments within emails will be forwarded as is without any additional processing.
7. The SMTP server should be available in the target country.

Getting Started

Let's assume that you already have configured SMTP server in the target country.

1. Creating service on the Portal

To create a new Email service for outbound emails, you should go to the InCountry Portal and follow the instructions.

2. Sending emails from your application

Let's assume that you already created your record with some user data on the InCountry platform via InCountry Web Services. Your created record has ID 006jkdsa00123oLpo and has the following structure in JSON:

{
  "record_key": "<uid>",
  "body": "{\"name\": \"Jepa\", \"email\": \"jepa@gmail.com\"}",
  "profile_key": "006jkdsa00123oLpo"
}

And now you would like to email this user from your application. Your application should send this email to the InCountry Email service in the following structure:

From: no-reply@yourapp.com
To: email@pk-006jkdsa00000oLpo.ru
Subject: Hello, %profile_key=006jkdsa00000oLpo,name%!

Dear %profile_key=006jkdsa00000oLpo,name%,
Welcome to this example email. What a lovely day!

As you can see, the email body and recipient address contain special placeholders.

• Email service will replace the To placeholder in the following way. First, Email service will look up the record with profile_key=006jkdsa00123oLpo and then use the email field from the record body field.
• For each placeholder in the email body, Email service will try to replace with a clear-text value from the record. For example, %profile_key=006jkdsa00123oLpo,name%. In this case, Email service will look up a record with profile_key=006jkdsa00123oLpo and then use the name field from the record body field.

In both situations above, Email service pulls the record's data from the InCountry platform and replaces placeholders with their actual values. Then Email service will send unredacted email (with replaced to the clear-text values placeholders) to the recipient address (from the To field) via your SMTP server, that provided in the Portal configuration from the step 1.

3. Troubleshooting

If something is not working (the recipient doesn't receive the email, etc.), you can view Email service logs on the Portal.

Email Service for Inbound Emails

How It Works

Typically, your users send emails to your mail server (for example, to your support email) with regulated data, violating local data regulations if your mail server is located in a country different from the sender's country of origin. To not violating local data regulations, you need to add your IMAP/SMTP mail server to the country of origin and put InCountry Email service in between the sender that sends inbound emails and your IMAP/SMTP server located in the sender's country of origin.

Email service via IMAP polls emails from your clients (senders) from your server that was added to the country of origin, and then redacts them. Once the data is redacted, it sends redacted emails to a mail server outside the country (e.g. support case management system, etc.) via your SMTP server.

Requirements

1. The IMAP and SMTP mail server should be available in the country of origin of the data.
2. Emails in the HTML and plain-text formats are supported.
3. Email service removes attachments from the redacted email and stores them in InCountry Vault.

Getting Started

Let's assume that you already have configured IMAP and SMTP server in the country of origin of the data.

1. Creating service on the Portal

To create a new Email service for inbound emails, you should go to the InCountry Portal and follow the instructions.

2. Receiving and redacting emails from users

Let's assume that your client write the following email to your support address support@corp.com, and this email address is served by mail server in the country of origin. The email from user:

From: jepa@gmail.com
To: support@corp.com
Subject: Some trouble

Hello! My account is blocked and SMS with code to unblock my account doesn't come. What should I do?

Email service in the country of origin pulls this email via IMAP and starts to redact it. The redacted email looks like the following:

From: <sender email that was provided during inbound Email service configuration on the Portal>
To: <recipient email that was provided during inbound Email service configuration on the Portal>
Subject: A new email case received on <timestamp, e.g. Mon 13, 2023 15:20:05 UTC+04>

Dear support team!
A new email case was received on <timestamp> from <from:emailMasking, e.g. j*******@gmail.com>. Please check the reported issue and reply to the requestor.

Email service creates a record in the InCountry Vault with the generated record_key and profile_key that are equals to the same value. The original values from the email are stored in the body field of this record and looks like the following JSON structure:

{
  "SuppliedEmail": "<just sender's email address without a name, e.g. jepa@gmail.com>",
  "FromAddress": "<just sender's email address without a name, e.g. jepa@gmail.com>",
  "SuppliedName": "<full email from address with name, e.g. 'Jepa Doe <jepa@gmail.com>",
  "FromName": "<full email from address with name, e.g. 'Jepa Doe <jepa@gmail.com>",
  "HtmlBody": "<original html body of the email>",
  "Description": "<description of the email>",
  "TextBody": "<original text body of the email>",
  "Subject": "<original subject of the email>",
  "ToAddress": "<emails separated by ';', e.g. alice@example.com; bob@example.com>",
  "CcAddress": "<emails separated by ';'>",
  "BccAddress": "<emails separated by ';'>",
  "to0": "<email>",
  ... // to1, ..., toN
  "cc0": "<email>",
  ... // cc1, ..., ccN
  "bcc0": "<email>"
  ... // bcc1, ..., bccN
}

Also, Email service will add custom header record_key to the redacted email headers containing the record key value of the record that contains the redacted email data. Then the Email service sends redacted email to the recipient address (provided in the inbound Email service configuration on the Portal) via your configured SMTP server (also provided in the Portal configuration in the step 1). These recipient address is served by mail service (e.g. support case management system, etc.) outside the country of origin. This system receives the redacted email with record_key in its headers and can get by record_key on its fronted side the original email data via InCountry Rest API, for example.

3. Troubleshooting

If something is not working (the recipient doesn't receive the email, etc.), you can view Email service logs on the Portal.

Managing Email service through Portal

Creating a new Email service

note

You can create one Email service per each activated country within an environment.

1. On the menu, select Environments.

2. Select the environment where you want to create the Email service.

3. On the opened list with countries, select the country where you want to create the Email service.

4. On the list of services, click Add service.

5. At the Select service step, select Email.

6. Click Next.

7. At the Email handling step, select the modes which the Email service will use:

   1. Inbound emails - the email gateway will redact inbound emails with clear-text sensitive values.
   2. Outbound emails - the email gateway will unredact outbound emails with redacted sensitive values.

8. Configure the parameters for the inbound email handling, as follows:

   1. IMAP server name - enter the address of the email service for the chosen mail provider, for example, mail.google.com.
   2. IMAP server - enter the address of the IMAP server, for example, imap.gmail.com.
   3. Port - enter the IMAP port to connect to the mailbox.
   4. Username - enter the username of the mail account for connecting through IMAP protocol.
   5. Password - enter the password of the mail account for connecting through IMAP protocol.
   6. Sender email - enter the email address which will be displayed in the From field.
   7. Salesforce service - select the Salesforce service which the Email service will operate for.
   8. Salesforce service mail address - enter the mailbox address that the Salesforce org allocated for this feature.
   9. Deterministic tokenization key - enter the deterministic tokenization key that the InCountry Data Residency for Salesforce package generated.
   10. SMTP server - enter the address of the SMTP server, for example, smtp.gmail.com.
   11. Port - enter the SMTP port to connect to the mailbox.
   12. Username - enter the username of the mail account for connecting through SMTP protocol.
   13. Password - enter the password of the mail account for connecting through SMTP protocol.

9. Configure the parameters for the outbound email handling, as follows:

   1. Apply SMTP settings to outbound email - move the toggle right if you want to re-use SMTP parameters and credentials from the Inbound emails section.
   2. SMTP Server - enter the address of the SMTP server residing in the country of origin (of your recipients).
   3. Port - enter the SMTP port to connect to the mailbox.
   4. Username - enter the username of the mail account for connecting through SMTP protocol.
   5. Password - enter the password of the mail account for connecting through SMTP protocol.

10. When complete, click Next.

11. At the Review step, review the configuration.

12. When complete, enter the verification code and click Create.

13. Once a new Email service has been created, you need to save the credentials and the address of the email gateway. You will need to use these values when connecting your application to the email gateway. To save these values as a TXT file, click Download. To copy these values to the clipboard, click Copy to Clipboard.

    note

    We show the Email service credentials only ones. Therefore, please copy this data and save it to some secure space on your side because you will not be able to view it again.

14. When complete, click Close.

Editing the Email service

1. On the list of services within an activated country, locate the Email service you want to edit.
2. Hover over the corresponding Email service and click the Edit service icon.
3. On the Email handling page, modify the connection details as needed. For the details on email parameters, please check the Creating a new Email service section.
4. When complete, click Next.
5. Enter the verification code and click Update. You may need to save the credentials and the address of the email gateway.
6. When complete, click Close.

Deleting the Email service

1. On the list of services within an activated country, locate the Email service you want to delete.
2. Hover over the corresponding Email service and click the Delete icon.
3. Enter the verification code.
4. Click Delete.

info

Please consider that after the removal of the Email service, emails will be neither redacted nor unredacted (depending on what modes were configured for the Email service). You may need to re-adjust your email workflows to restore the original functionality.

View Email service details

1. On the list of services within an activated country, locate the Email service of which you would like to see logs.
2. Hover over the corresponding Email service and click the Service details icon.
3. Here you can find only the Email SMTP address and port.

note

We show username and password for Email service only ones, during creation. If you forgot them, you should delete and create the new Email service with the same configuration. Please copy this data next time and save it to some secure space on your side because you will not be able to view it again.

View logs of the Email service

1. On the list of services within an activated country, locate the Email service of which you would like to see logs.
2. Hover over the corresponding Email service and click the View logs icon.
3. On the logs page, you can see the logs of your Email service that will help to debug your integration. Here on the page, you can also filter logs by different parameters. Logs records live 5 days. Also, you can download file with logs by clicking DOWNLOAD LOGS button.