Send and secure emails

You can send emails from your Grexx Platform application using the Send email system service. For example, you may configure an activity to send an email automatically when a new customer creates an account or when a task is overdue. In addition, the Invite user system service uses the Send email system service to send the email invitation to the invitee.

By default, emails are sent from [email protected]. Before making your application available to users in your Production environment, you may want to configure Grexx Platform to send emails from an email address on your own domain, such as [email protected].

To send emails from your own domain, you need to make changes to the DNS record for your domain:

• Add an SPF record to allow Grexx Platform to send emails from your domain.
• Add a DKIM record to allow Grexx Platform to sign the emails that it sends from your domain.
• Add custom TXT records to specify the Grexx applications and environments that are allowed to send emails from your domain.

Once you have updated your domain's DNS record, you can specify a custom From address when you configure activities that create Send email or Invite user cases.

Tip:

If you do not want to make changes to your domain's DNS record, you can use the Send email via custom SMTP system service to send emails via your SMTP server.

SPF record

Email servers use SPF (Sender Policy Framework) to fight spam. When an email server, such as outlook.com, receives an email from [email protected], the email server checks the SPF record in the DNS for somebank.com. If the SPF record shows that the IP address of the server that sent the email is allowed to send emails on behalf of somebank.com, then the email is delivered. If the sender is not listed in the SPF record, the email is marked as spam and may also be added to a public blocklist.

To ensure any emails you send from your application will be delivered, Grexx Platform performs an SPF check before sending the email. For example, if you configure an activity to send an email from [email protected], Grexx Platform checks the DNS for example.com to verify that the SPF record lists Grexx Platform as an authorized sender. If that's not the case, the email is not sent and an error is returned.

To allow Grexx Platform to send emails from your domain, add include:_spf.grexx.today to your SPF record in the DNS. An example full SPF record would then read:

v=spf1 include:_spf.grexx.today ~all

Note:

Before making changes to your SPF record, refer to your domain registrar's documentation.

DKIM record

Email servers use DKIM (DomainKeys Identified Mail) to minimize phishing attacks and other scams. With DKIM, the server sending the email adds a cryptographic signature to the message. The receiving email server verifies this signature to ensure the sender has not been impersonated and that the message has not been tampered with.

To allow Grexx Platform to sign emails sent from your domain, add the following CNAME records in the DNS:

• A CNAME record on grexxplatform1._domainkey.your-domain.com pointing to grexxplatform1._domainkey.grexx.net
• A CNAME record on grexxplatform2._domainkey.your-domain.com pointing to grexxplatform2._domainkey.grexx.net

For example, to send emails with a From address of [email protected], add grexxplatform1._domainkey.example.com and grexxplatform2._domainkey.example.com to the DNS record for example.com.

Use a DKIM check tool such as MX Toolbox to verify that the records are configured correctly. Specify your domain (example.com in the above example) and test both grexxplatform1 and grexxplatform2 as the selectors.

Once you have updated the DNS and verified the records, contact your Grexx coach and ask them to enable email signing for your domain name.

Custom TXT records

Once you have enabled Grexx Platform to send emails from your domain by configuring SPF and DKIM records, you need to specify the Grexx application(s) that you want to allow to send those emails. You do this by adding custom TXT records to the DNS record for your domain.

Identify Grexx application environments

Each of your Grexx application's environments (Development, Testing, Acceptance, and Production) has a unique platform ID. You can view the platform ID for each environment from MyGrexx. The platform ID also makes up the second part of the case ID for all cases in a particular DTAP environment. For example, if a case ID from your Production environment is 1:123:456, then 123 is the platform ID for your Production environment.

To identify the application(s) that you want to allow to send emails from your domain, you need to add a TXT record that maps the gp-mail-platform key to the platform ID(s) of the relevant application environment(s). If you cannot fit everything into a single TXT record, you can add multiple TXT records with the same keys. As long as one of the TXT records matches the requirements for the outgoing email, Grexx Platform will allow the email to be sent.

You can also add additional keys as described below. Each key should be added in a separate TXT record on the root (typically indicated by @ in the DNS record) of your domain. For information about how to add TXT records to your domain's DNS record, refer to your domain registrar's documentation.

Key with example	Description
gp-mail-platform=1234, 1237	Application environments 1234 and 1237 can send emails from your domain.
gp-mail-address = [email protected], [email protected]	Only allow email to be sent from [email protected] and [email protected]. If this key is not specified, any address from your domain can be specified in the From field.
gp-mail-allow-all-platforms = true	Allow all Grexx applications and environments to send emails from your domain. Not recommended.

Tip:

Development, Testing, Acceptance, and Production all have different platform IDs. If you want to test sending emails from your domain from your Testing or Acceptance environment, you need to include the relevant platform ID(s) in the gp-mail-platform key.

Multi-tenant environments

Some Grexx applications are multi-tenant, meaning that multiple different customers (tenants) use the same application as their own. If you are developing a multi-tenant application, you may want to enable a tenant to send emails from their own domain without allowing other tenants to send from that domain. To achieve this you need to:

1. Ask the tenant to add the gp-mail-platform key to their domain's DNS to identify the multi-tenant application (as described above).
2. Ask the tenant to add the gp-mail-tenant key as a TXT record to their domain's DNS with a unique value that identifies their organization.
3. Record the tenant key value in an attribute on the tenant's Organization case (or similar) and map this value to the SPF Tenant Key field when you create a Send email or Invite user case.

A tenant key value may consist of letters (az and AZ), digits (0-9), the dash (-), underscore (_), or colon (:). There is no maximum length, but to keep things running smoothly we recommend keeping each key between 4 and 16 characters. For example, you might specify the tenant name (acme-inc), case ID (1:123:456), or allocate a randomly generated string (b4nvke9).

Tenant keys should be added as TXT records to the DNS of the tenant's domain. As with the records above, each key should be added in a separate TXT record on the root level of the domain.

Key with example	Description
gp-mail-tenant = 1:1234:5, abc	Tenants 1:1234:5 and abc are allowed to send emails on behalf of this domain. Required for multi-tenant platforms.
gp-mail-allow-all-tenants = true	Allow all tenants on this platform to send emails on behalf of this domain. (Optional)

When a Send email or Invite user case is created with a custom domain in the From field, Grexx Platform checks the DNS entry for that domain to verify that:

• The application is authorized to send emails from that domain (based on the gp-mail-platform key).
• The tenant identified in the SPF Tenant Key field is authorized to send emails from that domain. If the value in the SPF Tenant Key field is not listed in the DNS entry for the domain, the email is not sent and an error is returned.
  Note that if you specify multiple tenant keys in the SPF Tenant Key field, an any-in match is performed.

Additional configuration (MyGrexx)

You can set the following configuration flags from MyGrexx to ensure TXT records are in place to control which application environments can send emails from your domain:

• SPF platform strict: If true then gp-mail-platform or gp-mail-allow-all-platforms must be set in the DNS. If neither key is set, an error is returned.
  This configuration flag is set to true by default from Grexx Platform version 10.11 onwards. Note that this flag is deprecated and the option to set it to false will be removed in future.
• SPF tenant strict: If true and an SPF tenant key is specified in a Send Email or Invite User system service case, then gp-mail-tenant or gp-mail-allow-all-tenants must be set in the DNS. If neither key is set, an error is returned. We recommend setting this option to true on multi-tenant platforms.