E-mail

Table of сontents

• Creating a new Email service
• Email Gateway
  • Email handling workflow
  • Email requirements
  • Configuration of Email Gateway
  • Handling placeholders within emails

The Emails service uses an email gateway that 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 while saving this sensitive data to the InCountry Vault. After this, Email Gateway 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

Creating a new Email service

note

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

1. On the menu, select Environments.
2. On the opened list with environments or on the sidebar, select the environment where you want to create the Payments service.
3. On the opened list with countries or on the sidebar, select the country where you want to create the Payments service.
4. On the list with 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. Please check the IMAP port of your mail provider.
   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 once it is delivered to Salesforce.
   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 the Email-to-Case 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. Please check the SMTP port of your mail provider.
   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. Please check the SMTP port of your mail provider.
   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 Text. To copy these values to the clipboard, click Copy to Clipboard.
14. When complete, click Close.

Email Gateway

Email Gateway is a part of InCountry Border. It resides between the customer’s application (SaaS platform) that sends outbound emails and the customer’s SMTP server located in the recipient’s country of origin. It 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 the customer’s SMTP server that further delivers this email to target recipients.

Email handling workflow

Typically, a client 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. With the InCountry platform, the client application sends an email with placeholders containing hashed values to Email Gateway that identifies them and retrieves regulated data from the InCountry platform against the specific identifiers. Email Gateway replaces these placeholders with the recipient’s name and email address in the TO, FROM, SUBJECT, and BODY fields of the outbound email. Then it sends the email with clear-text values to the customer’s SMTP server that delivers an email with regulated to the recipient.

Email Gateway works in conjunction with InCountry Border and uses the shared configuration that defines SMTP authentication credentials for the customer’s SMTP server. The customer’s SMTP server must be in the recipient’s country of origin so that no compliance regulations are violated.

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

Email requirements

Email Gateway 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.
4. The From and To fields should contain redacted email addresses of the specific pattern, like email@profile_key006jkdsa00000oLpo.se.
5. 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%.
6. Emails in the HTML and plain-text formats are supported.
7. Attachments within emails will be forwarded as is without any additional processing.
8. The customer’s SMTP server should be available in the target country.

Configuration of Email Gateway

Configuration of Email Gateway is a part of InCountry Border configuration. Below you can find a typical configuration of Email Gateway:

{
  "country": "IN",
  "environmentId": "a4a3221c-zzzz-yyyy-xxxx-86edae5cee0a",
  "oauth": {
    "clientId": "58e5ccf4-xxxx-xxxx-xxxx-abf4404ad99d",
    "clientSecret": "tXjnUvG5FX7qMFDWAUhzIWJEv2"
  },
  "vaultEncryptionKeyPath": "/v1/staging-portal-generation/export/encryption-key/in.a4a3221c-zzzz-yyyy-xxxx-86edae5cee0a",
  "email": {
    "client": {
      "host": "smtp.company.com",
      "port": 25,
      "username": "username123",
      "password": "mTLEY00tQHmy1kprS2HhAg"
    }
  }
}

Within the Email Gateway configuration you need to define the following parameters:

Parameter	Tolerated values	Description
country	IN or SA (or any other country ISO code)	A code of the country which is used to construct a PoP API request.
environmentId		A unique identifier of the environment for storing regulated data.
oauth		OAuth 2.0 credentials giving access to the environment on the InCountry platform in the target country. Here the clientId and clientSecret are specified.
email		A list of email connection parameters to the SMTP server in the target country.
host	smtp.company.com	Address of the SMTP server which emails are proxied to.
port	- 25 - 465 - 587 - 2525	SMTP port that is used for sending emails.
username	username123	Client ID that is used for SMTP authentication.
password	mTLEY00tQHmy1kprS2HhAg	Client Secret that is used for SMTP authentication.

Handling placeholders within emails

Email Gateway receives an email and parses it to the JSON object, as follows:

{
  "from": "john.doe@mail.com",
  "to": "jane.doe@mail.com",
  "subject": "Hello, %profile_key=006jkdsa00123oLpo,name%! Personal discount update notification",
  "text": "Hello, %profile_key=006jkdsa00123oLpo,name%! \n ✔ Your current discount is %profile_key=006jkdsa00000oLpo,amount%! test"
}

The email body is placed within the text property that should have a pre-defined structure.

• For each record, you need to specify a placeholder that will be further replaced with a clear-text value from the record, for example, %profile_key=006jkdsa00123oLpo,name%. In this case, Email Gateway through InCountry Border will look up a record with profile_key=006jkdsa00123oLpo and then use the name field from the payload (the body field). In such situation, Email Gateway pulls the record's data from the InCountry platform and replaces placeholders with their actual values:

{
  "recordKey": <uid>,
  "body": JSON({"name": "John", "amount": 100}),
  "profile_key": "006jkdsa00123oLpo",
  ...
}