All Collections
Workspace management
Creating and setting up your workspace
How to set up your business email domain to use it in Cerby
How to set up your business email domain to use it in Cerby

This article describes how to grant access to Cerby to use your business email domain via an Amazon SES integration.

Cerby Team avatar
Written by Cerby Team
Updated over a week ago

Cerby can leverage your current business email domain to manage the email accounts you create and use for authentication and security purposes. This article describes how to grant access to Cerby to use your domain via an Amazon Simple Email Service (SES) integration.

Supported features

The following are the supported features for bringing your business email domain to Cerby:

  • Email account creation from Cerby: This process occurs when users create email accounts from Cerby with their business email domain for authentication and security purposes.

Requirements

The following are the requirements to bring your business email domain to Cerby:

  • An account in Cerby with a Workspace Owner role.

  • An AWS account and access to a business email domain registered in the Domain Name System (DNS), or an already implemented Amazon SES integration.

  • Permission for accessing AWS CloudShell and adding Identity and Access Management (IAM) roles in AWS.

    IMPORTANT: Cerby recommends using AWS CloudShell because it contains the tools and libraries needed to configure Amazon SES.

Set up your business email domain to use it in Cerby

To bring your business email domain to Cerby, you must complete two or three of the following steps depending on whether you have an Amazon SES integration implemented or not:

  1. Configure Amazon SES to send and receive emails

  2. Grant access to Cerby to your Amazon SES integration

  3. Configure your Cerby workspace to use your business email domain

    IMPORTANT: Complete steps 2 and 3 if you have an Amazon SES integration implemented, which means being able to send and receive emails through an existing configuration. Complete the three steps if and only if you have an AWS account and access to a business email domain (this domain might be managed by Amazon Route 53).

The following sections describe each main step.

1. Configure Amazon SES to send and receive emails

To configure Amazon SES to send and receive emails, complete the following steps:

  1. Log in to the AWS Console.

  2. Open an AWS CloudShell terminal.

    IMPORTANT: AWS CloudShell is not supported in all of AWS Regions. For a list of the supported regions and associated service endpoints, see AWS CloudShell endpoints and quotas.

  3. Run the following command to clone the repository:

    $ git clone https://github.com/cerbyinc/cerby-aws-ses-integration.git

  4. Run the following command to execute the Cerby AWS SES Configuration tool:

    $ python3 main.py <your_domain>

  5. Enter y to add the DomainKeys Identified Mail (DKIM) records to the hosted zone.

  6. Enter y to add the Mail Exchanger (MX) record to the hosted zone. One of the following two scenarios occurs:

  7. Request AWS for production access to Amazon SES by following the instructions from the Moving out of the Amazon SES sandbox article.

    IMPORTANT: Amazon SES is configured by default in the sandbox. If you omit to request production access, you will not be able to send emails to any recipient.

Now you are able to send and receive emails via Amazon SES with your business email domain.

2. Grant access to Cerby to your Amazon SES integration

To grant access to Cerby to use your Amazon SES integration on your behalf, you have two options:

The following subsections describe the steps of each option.

CloudFormation template

To leverage a CloudFormation template for granting access to Cerby to use your Amazon SES integration, complete the following steps:

  1. Log in to the AWS Console.

  2. Access the following URL in the address bar of your browser:

    https://console.aws.amazon.com/cloudformation/home?region=us-east-1#/stacks/quickcreate?stackName=cerby-aws-ses-integration&templateURL=https://cerby-public-assets.s3.us-east-2.amazonaws.com/cerby-aws-ses.yaml&param_RoleName=cerby-aws-ses-integration-role&param_EmailAddress=change@me.com&param_ExternalId=changeme

    The Quick create stack page of the CloudFormation service is displayed with values prefilled in the Template, Stack name, and Parameters sections.

  3. Perform the following actions to modify the corresponding values:

    • Enter an email address in the EmailAddress field. This email address is used by Cerby to forward messages. For example, hello@cer.dev.

    • Enter an external ID in the ExternalId field. This ID is used along with the role. For example, CerbyID.

      IMPORTANT: Make sure to enter the external ID without spaces.

      NOTE: You can modify the values of the Stack name and RoleName fields to the stack name and role name of your choice, respectively.

  4. Click the Next button. The Configure stack options page is displayed.

    NOTE: Adding tags in the Configure stack options page is optional. You can go to the next step without adding tags.

  5. Click the Next button. The Review <stack name> page is displayed.

  6. Select the “I acknowledge that AWS CloudFormation might create IAM resources.” option from the Capabilities section located at the bottom of the page.

  7. Click the Create stack button. A page with the details of the new stack is displayed.

    NOTE: The process of creating the stack may take a while, and you can verify its status in the Overview section of the Stack info tab. Click the Refresh button to refresh the page. The Status field must change from CREATE_IN_PROGRESS to CREATE_COMPLETE.

Now you have granted access to Cerby to use your Amazon SES integration.

Manual configuration

To manually configure granting access to Cerby to use your Amazon SES integration, complete the following steps:

  1. Create a role

  2. Create a policy

  3. Attach the new policy to the new role

  4. Edit the trust relationship

The following subsections describe each main step.

1. Create a role

To create a role, complete the following steps:

  1. Log in to the AWS Console.

  2. Access the IAM dashboard.

  3. Click the Roles option from the Access management list in the left-hand side navigation drawer. The Roles page is displayed.

  4. Click the Create role button located in the upper-right corner of the window. The Create role page is displayed.

  5. Select the Another AWS account option from the Select type of trusted entity section. The Specify accounts that can use this role section is displayed.

  6. Perform the following actions to specify the Cerby account in AWS that can use this role:

    1. Enter 749452252575 in the Account ID field.

    2. Select the Require external ID option. A message box is displayed for you to provide an external ID.

    3. Enter an identifier in the External ID field. For example, CerbyID.

  7. Click the Next: Permissions button located in the bottom-right corner of the window. The Attach permissions policies section is displayed.

2. Create a policy

To create a policy for the new role, complete the following steps from the Attach permissions policies section:

  1. Click the Create policy button. The Create policy page is displayed in a new window with the Visual editor tab activated.

  2. Activate the JSON tab to open the JSON page with a code block.

  3. Enter the following information in the code block:

    {
        "Version": "2012-10-17",
        "Statement": [
            {
                "Action": [
                    "ses:CreateReceiptRule",
                    "ses:CreateReceiptRuleSet",
                    "ses:DeleteReceiptRule",
                    "ses:DeleteReceiptRuleSet",
                    "ses:DescribeReceiptRule",
                    "ses:DescribeReceiptRuleSet"
                ],
                "Resource": "*",
                "Effect": "Allow"
            },
            {
                "Sid": "VisualEditor0",
                "Effect": "Allow",
                "Action": "ses:SendEmail",
                "Resource": "*",
                "Condition": {
                    "StringEquals": {
                        "ses:FromAddress": "<your_email_address>"
                    }
                }
            }
        ]
    }

    NOTE: Enter the email address you want Cerby to use to forward messages as the ses:FromAddress value. For example, hello@cer.dev.

  4. Click the Next: Tags button. The Add tags (Optional) section is displayed to add key-value pairs that help you identify, organize, or search for resources.

    NOTE: Adding tags is optional, so you can go to the next step without them.

  5. Click the Next: Review button. The Review policy section is displayed.

  6. Enter a policy name in the Name field. For example, CerbyPolicy.

    NOTE: Adding a policy description in the Description field is optional. You can go to the next step without adding a description.

  7. Click the Create policy button. The Policies page is displayed with a successful message.

3. Attach the new policy to the new role

To attach the new policy to the new role, complete the following steps:

  1. Go back to the Create role page with the Attach permissions policies section.

  2. Click the Refresh button to refresh the list of policies.

  3. Enter the name of the new policy in the Search bar to find it. In this case, it is CerbyPolicy.

  4. Select the checkbox of the new policy.

  5. Click the Next: Tags button. The Add tags (optional) section is displayed.

    NOTE: Adding tags is optional; they help you organize, track, or control access for this role. You can go to the next step without adding tags.

  6. Click the Next: Review button. The Review section is displayed.

  7. Enter a role name in the Role name field. For example, cerby-aws-ses-integration.

    NOTE: Adding a description in the Role description field is optional. You can go to the next step without adding a description.

  8. Click the Create role button. The Roles page opens with a successful message.

4. Edit the trust relationship

To edit the trust relationship of the new role, complete the following steps from the Roles page:

  1. Click the new role; in this case, its name is cerby-aws-ses-integration. The Summary page of the new role opens.

  2. Activate the Trust relationships tab to open the Trust relationships page.

  3. Click the Edit trust relationship button. The Edit Trust Relationship page opens with a policy document and a code block.

  4. Edit the policy document, so it looks like the following code block:

    {
      "Version": "2012-10-17",
      "Statement": [
        {
          "Effect": "Allow",
          "Principal": {
            "AWS": "arn:aws:iam::749452252575:role/customer-assumable-roles"
          },
          "Action": "sts:AssumeRole",
          "Condition": {
            "StringEquals": {
              "sts:ExternalId": "<external_ID>"
            }
          }
        }
      ]
    }

    NOTE: Enter the external ID that you previously assigned. In this case, CerbyID.

  5. Click the Update Trust Policy button. The Summary page is displayed.

    TIP: Keep the Summary page of the new role open. You need the Amazon Resource Name (ARN) of the role to configure the workspace email in Cerby.

Now you have granted access to Cerby to use your Amazon SES integration.

3. Configure your Cerby workspace to use your business email domain

To configure your Cerby workspace to use your business email domain, complete the following steps:

  1. Log in to your corresponding Cerby workspace.

  2. Select the Settings option from the left navigation drawer. The Workspace Configuration page is displayed with the General tab activated.

  3. Click the Configure Email button located in the Workspace Email Configuration section. The Create workspace configuration email dialog box is displayed.

  4. Perform the following actions to configure the workspace email:

    • Select the corresponding AWS Region option from the Select a region drop-down list in the Region field.

      NOTE: Currently, the available options for receiving emails are us-east-1, us-west-2, and eu-east-1.

    • Enter your AWS Account ID in the Account ID field. For example, 123456789123.

    • Enter the external ID you assigned for the role in the External ID field. In this case, CerbyID.

    • Enter the ARN of the role in the ARN Role field.

      TIP: Copy the ARN of the role from the Summary page that you left open.

    • Enter the email address in the Email Address field. In this case, hello@cer.dev.

      IMPORTANT: The email address must be the same that you assigned when granting access to Cerby to your Amazon SES integration.

    • Enter the business email domain in the Domain field. Cerby uses this domain to generate email addresses.

  5. Click the Save button. The Create workspace configuration email dialog box closes, and a successful message is displayed on the Workspace Configuration page.

Now you are done.

Troubleshooting: Configure your DNS server manually when not using Amazon Route 53

When you configure Amazon SES to send and receive emails with your business email domain in Cerby, but you don’t use Amazon Route 53 as your DNS service provider, you must configure your DNS server manually.

The Cerby AWS SES Configuration tool provides you with the corresponding DNS records you need, as described in the instructions of the 1. Configure Amazon SES to send and receive emails section.

The records and rules you must configure are the following:

  1. NS records

    1. Configure the nameserver (NS) records for your domain and subdomain in your DNS domain registrar.

  2. MX record

    1. Configure the MX record of your domain or subdomain in your DNS domain registrar to point to the inbound SMTP domain of AWS. For example, if you use the us-west-2 region, the inbound SMTP domain must be inbound-smtp.us-west-2.amazonaws.com. Reference the Amazon Simple Email Service endpoints and quotas article to identify the Email Receiving Endpoint for the region you used for the deployment.
      For more information on how to configure an MX record, read the official documentation from your DNS service provider, such as the following:

  3. DKIM records

    1. Configure the DKIM records for your domain and subdomain in your DNS domain registrar.
      For more information on how to configure a DKIM record, read the official documentation from your DNS service provider, such as the following:

    2. Create a domain identity in Amazon SES with the following configuration:

      • Easy DKIM as the identity type

      • RSA_2048_BIT as the DKIM signing key length

      • DKIM signatures enabled

    3. Verify the DKIM domain identity with your DNS provider.

      For more information on how to create and verify a domain identity, read the Creating and verifying identities in Amazon SES official documentation from AWS.

  4. Email receipt rule

    1. Configure the PROXY-MAIL rule in the AWS SES dashboard with an action to deliver the received emails to the cerby-store-ses-email-production Amazon S3 bucket.

      For more information on how to configure an email receipt rule, read the Creating receipt rules console walkthrough official documentation from AWS.

Troubleshooting: I have already created Cerby-managed email addresses

When you have already created email addresses with the Cerby domain but want to start using your business domain, you must remove all of the existing email addresses from your accounts before the setup.

Cerby doesn’t support having both email addresses with a Cerby domain and business domain at the same time. If this happens, the messages sent to the existing Cerby domain email addresses will not be routed to your workspace.

If you need assistance in identifying the accounts with Cerby-managed email addresses contact the Customer Support team by sending an email to support@cerby.com or a message through the help chat of the Cerby dashboard.

Did this answer your question?