Email UI

From the Email page of the SBS portal, you can perform the following actions:

• Send email to one or multiple TO, CC, or BCC recipients. You can send email: a) from the default email address no-reply@socrate.email b) from a custom, verified email address, c) from any email address of a verified domain, d) from a Google or Microsoft address authorized via app password.
• View the inbound email for the currently selected account/app/tenant.
• View the outbound email for the currently selected account/app/tenant.
• View and configure the email accounts entitled to send email from SBS (also known as “email identities”), and their verification status (pending, verified).
• View and configure the third-party email accounts verified by app-password that are entitled to send email from SBS.
• View and configure the Internet domains entitled to send email from SBS (also known as “domain identities”), and their verification status (pending, verified).
• View and configure the email domain at which all email is received for the current account/app/tenant (also known as the “inbound domain”).
• Debug failed email delivery. More specifically, you can view whether a particular email address is blocked for email delivery by the Amazon SES suppression list. You can also remove an email address from the Amazon SES suppression list if it’s found there. For details, see Address Status (Amazon SES suppression list).

Access

You can access the Email page of the portal as follows:

1. Sign in to the SBS Portal. During the sign-in process, you will be prompted to select the account, app, and tenant where you are entitled to sign in.
2. Click email-api in the left hand-side menu.

To interact with the Email service, you can use either the Web UI or a GraphQL interface. You can switch at any time between the two interfaces by clicking the switch displayed at the top of the page:

Send email

To send an email:

1. Click the Compose button available in the top-right corner of the page. A dialog box pops up.
2. Fill in the fields as required. The only mandatory field is TO. (Alternatively, use the CC or BCC fields.)
3. Click Send.

Note the following:

• To add multiple recipients in the TO, CC, and BCC fields, separate the email addresses by a comma.
• If you do not specify a From email address, the email message will be sent from the default email address no-reply@socrate.email.
• If you specify a From email address, it must be (a) a verified email address, (b) an email address from a verified domain, or (c) a Google or Microsoft address authorized via app password.
• Fill in the App password and App Password Provider fields only if you intend to use the scenario (c) above. However, if you opted to store your app password in SBS, then you may leave these fields empty.
• For more information about all the input parameters, see the API Reference.

Inbound email

To view the inbound email, click the Inbox tab. By default, the grid shows email messages received within the past 7 days. To show messages for a different time period, select a different date interval from the Created at Date picker.

Click a row in the grid to display a dialog box with full details about a particular email message.

Outbound email

To view the outbound email, click the Sent tab. By default, the grid shows email messages sent within the past 7 days. To show messages for a different time period, select a different date interval from the Created at Date picker.

Click a row in the grid to display a dialog box with full details about a particular email message.

Email identities

This tab displays email accounts for which a verification request was initiated, and the actual verification status. The verification status may be one of the following:

• PENDING - this status indicates that a verification request was initiated (and instructions were sent to that email address), but the email address has not been verified yet. Email addresses having PENDING status cannot send email.
• VERIFIED - the email address verification has completed successfully and the email address can send email.

You can verify email addresses either at application level or tenant level.

If you verify an email address at application level, then any tenant under that app will be able to send email from the verified email address (that is, use it in the From field when sending an email). For information about verifying email accounts at application level, see Verify an email identity at application level.

If you verify an email address at tenant level, then only that specific tenant will be able to send email from the verified email address.

Verify an email identity at tenant level

To verify an email address at tenant level:

1. Sign in to the SBS Portal.

2. Click Email in the left hand-side menu.

3. Click the Email Identities tab.

4. Click Add . A dialog box pops up.

   

5. Enter the email address to be verified, and then click Verify. As a result, you will receive four email messages at the specified email address.

   Three email confirmations are for the three different regions in the Amazon Web Services (AWS) global infrastructure. SBS relies on AWS regions in order to provide high availability. The fourth email confirms the SBS application as a valid sender to use in the “from” field when sending email.

6. For each of the received email, click the confirmation link. This authorizes the corresponding inbox to send emails through the Email Service API.

7. Wait a few minutes and then refresh the Email Identities grid. The email identity status should change to VERIFIED.

Once the status is VERIFIED, you can send email using that email address (identity).

GraphQL

If you prefer to use GraphQL:

1. Run the verifyEmailIdentity mutation of the Email Service and supply the email address to be validated as input. As a result, you will receive four email messages at the specified email address.

mutation verifyEmail($input:EmailAddress!) {
  verifyEmailIdentity(address:$input) {
    address
    status
  }
}

{
  "input": "YOUR_EMAIL_ADDRESS"
}

2. For each of the received email, click the confirmation link. This authorizes the corresponding inbox to send emails through the Email Service API.

To view the current status of email identities (verified or pending verification), run the emailIdentities query, for example:

query emailIdentities{
  emailIdentities{
    items {
      address
      status
    }
  }
}

Delete an email identity

To delete previously created email identities, click the Remove button. The outcome of deleting an email identity is that the user will no longer be able to send email using that identity.

GraphQL

You can delete previously created email identities by running the deleteEmailIdentity mutation. The outcome of deleting a verified email identity is that the user will no longer be able to send email using that identity.

App password accounts

This tab displays Google or Microsoft email addresses that were authorized to send email via app password. For information about authorizing Google or Microsoft accounts to send email from SBS, see Sending email from a Google or Microsoft 365 email address.

Note that email accounts present in this list may or may not be able to send email, depending on whether the app password is still valid. For example, the email account cannot send email if the user has deleted the app password from their Microsoft of Google account.

Store an app password

Storing an app password in SBS is optional. This enables you to reuse the app password when sending email instead of having to enter it manually each time.

To store an app password:

1. Sign in to the SBS Portal.

2. Click Email in the left hand-side menu.

3. Click the App Password Accounts tab.

4. Click Add . A dialog box pops up.

5. Enter the Google or Microsoft email address and the app password. For instructions about obtaining an app password, see Obtaining a Google App Password and Obtaining a Microsoft 365 App Password.

6. Select the email provider (GOOGLE or MICROSOFT, as applicable).

   

7. Click Add.

You can now use the email address in the From field when sending an email, without having to enter its associated app password.

Update an app password

To update an existing app password:

1. Click the app password account ID (the first column in the grid).
2. Enter the new app password, and then click Save.

Delete an app password

To delete an app password, click the Remove button. Note that removing an app password from SBS does not remove it from your Google or Microsoft account.

Domain identities

This tab displays Internet domains for which a verification request was initiated. The verification status may be one of the following:

• PENDING - this status indicates that a verification request was initiated, but the domain DNS information has not been added or propagated yet. Domains having PENDING status cannot send email.
• VERIFIED - the domain verification has completed successfully and any email from that domain can send email.

Verify a domain identity at tenant level

To verify a domain identity:

1. Sign in to the SBS Portal.

2. Click Email in the left hand-side menu.

3. Click the Domain identities tab.

4. Click Add . A dialog box pops up.

   

5. Enter the internet domain to be verified, and then click Add. The domain record should now appear in the grid with the PENDING status.

   

6. Click the DNS Records button. A dialog box opens that contains a list of DNS entries.

   There are three DNS records for each of the three regions in the Amazon Web Services (AWS) global infrastructure, which makes nine DNS records in total. The tenth DNS record authorizes the tenant to send emails with SBS.

   

7. Add to your domain’s DNS records the ten new DNS records as given above. The instructions will vary depending on your domain provider.

GraphQL

If you prefer to use GraphQL:

1. Run the verifyDomainIdentity mutation and provide as input the name of the email domain to be verified. In the response, you will get a list of ten DNS records.

mutation verifyDomain($input:Domain!) {
  verifyDomainIdentity(domain:$input) {
    domain
    status
    dnsRecords {
      type
      name
      value
    }
  }
}

{
  "input": "example.org"
}

2. Add to your domain’s DNS records the ten new DNS records received previously.

To view the list of domain identities and their verification status, run the domainIdentities query, for example:

query domainIdentities {
  domainIdentities {
    items {
      domain
      status
      dnsRecords {
        type
        name
        value
      }
    }
  }
}

Inbound email

This tab displays the domain that was registered as inbound domain for the current tenant, if any. For example, if this value is my.app.socrate.email, then all email sent to this email domain will be received by the current tenant and visible in the Inbound tab. Examples:

• sales@my.app.socrate.email
• support@my.app.socrate.email
• any.recipient@my.app.socrate.email

If there is no registered subdomain yet, then a Register inbound email button is displayed instead.

Register an email subdomain at tenant level

Registering an email subdomain at tenant level is required before you can receive any email.

To register an email subdomain at tenant level:

1. Sign in to the SBS Portal.

2. Click Email in the left hand-side menu.

3. Click the Inbound Domain tab.

4. Click Register Inbound Email. At this stage, you may see an error message that the inbound subdomain should be configured at application level first. If you see this message, sign in to the SBS Console and perform this step, as described in Register an inbound subdomain at application level. Otherwise, you should see a a dialog box like the one below:

   

5. Enter the tenant subdomain to use. This string must be unique for each tenant if there are multiple tenants using the same app.

6. Click Save.

The configured inbound domain should now be displayed on the page. For example, if the inbound domain is ten.app.socrate.email, then any email recipient like {any-recipient}@ten.app.socrate.email will now reach your app.

GraphQL

If you prefer to use GraphQL, you can register a tenant subdomain by running the registerSubdomain mutation of the Email Service, for example:

mutation register_subdomain($input:RegisterSubdomainInput!){
  registerSubdomain(input:$input) {
    domain
    subdomain
  }
}

Make sure to use a subdomain name that is descriptive of your tenant:

{
  "input":{
    "subdomain": "YOUR_SUBDOMAIN_NAME"
  }
}

The result is similar to the following:

{
  "data": {
    "registerSubdomain": {
      "domain": "ten.app.socrate.email",
      "subdomain": "ten"
    }
  }
}

In the code listing above, the tenant subdomain is ten and the app subdomain is app. Therefore, any email sent to an address like recipient@ten.app.socrate.email will now reach your app.

Delete a registered subdomain

To delete a tenant-level email subdomain this, click the Delete Inbound Email Subdomain button. Be aware that the button is available only if the inbound email domain has already been configured.

Address status (Amazon SES suppression list)

The Address Status tab provides a tool that is helpful to debug failed email delivery to certain email addresses.

To deliver email to recipients, SBS relies on Amazon Web Services (AWS). As part of its Amazon Simple Email Service (SES) offering, AWS maintains a list of email addresses that are suppressed for delivery, called Amazon SES suppression list. An email address may be added by AWS to the suppression list if delivery to that email address has failed due to various reasons.

To view whether an email address is on the Amazon SES suppression list:

• On the Address Status tab, enter the email address of interest, and then click Query Status.

If the returned status is OK, the email address is not on the suppression list and email delivery to this email address is not blocked by AWS.

If the returned status is SUPPRESSED, delivery to that email address is blocked by AWS, and the reason is displayed accordingly, for example:

You can remove the email address from the suppression list if necessary. To do this, click Unsuppress. Note that this button is available only if the email address was actually found on the Amazon SES suppression list.

When you click Unsuppress, a request is sent to AWS to remove the email address from the suppression list and the outcome is displayed on the page. If the returned status is OK, the email address has been successfully removed from the suppression list.