Email Service

Access info

Usage

The Email Service enables you to send email using any of the following approaches:

• From the default email address no-reply@socrate.email. For more information, see Sending email from the default email address.
• From a custom email address such as sales@some.company. For more information, see Sending email from a custom email address.
• From any email address at some custom domain, for example, laura@some.company, bob@some.company, etc. For more information, see Sending email from any address of a custom domain.
• From a custom email address managed by Google or Microsoft 365®. This may be an email address such as example@gmail.com, example@live.com or a personalized email address such as example@some.company. For more information, see Sending email from a Google or Microsoft 365® email address.

When sending email with attachments, the attachments can either be files previously created through the File Management Service, or public file URIs.

Optionally, when sending email, you can apply email templates created previously through the Document Rendering Service.

You can obtain a list of sent messages by running the messages query. Detailed filtering options are available. The query results include, among other information, the delivery status of each message. If there were multiple recipients in the to, cc, and bcc fields, the delivery status is available for each recipient.

Optionally, you can enable tracking engagement for sent messages. This enables you to obtain information about the number of times the email was opened, and when. For messages sent in HTML format, you can track which links contained in the email were clicked, and when.

The Email Service also provides the ability to receive email at any address that has the following format:

 {recipient}@{tenant_subdomain}.{app_subdomain}.socrate.email

where {recipient}, {tenant_subdomain}, and {app_subdomain} are configurable. For example, you could configure your app to accept email at an address like sales@tax.ebs.socrate.email or support-123456@yyy.zzz.socrate.email. For more information, see Receiving email.

You can obtain a list of incoming messages by running the InboundMessages query. Detailed filtering options are available.

Sending email from the default email address

This is the most simple way of sending emails and it does not require any email inbox or domain verification. When running the sendMessage mutation, the only required parameters are at least one of the following (or any combination of): to, cc, and bcc. Secondly, you do not need to provide a value for the from parameter. The From field of the email will be automatically set to no-reply@socrate.email.

For a step-by-step example, see Tutorial: Send an email.

Sending email from a custom email address

To send email from an email address such as example@some.tenant or example@some.app, you must first verify that email address. Verification means that the bearer of the service access key will be able to use the verified email address in the “from” field when sending email through the sendMessage mutation.

There are two possible implementation scenarios:

1. Your application needs to allow all its tenants to send email from an email address like example@some.app. In this case, you should verify the email address at application level, as described in Verify an email identity.
2. A specific tenant needs to send email only on their own behalf, from their own custom address such as example@some.tenant. In this case, you should verify the email address as described below under “Email identity verification at tenant level”.

Email identity verification at tenant level

Verification of an email identity is a one-time procedure and it consists of the following steps:

1. Run the verifyEmailIdentity mutation 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
    }
  }
}

Once you have verified the email inbox, you can use this value in the from input parameter when running the sendMessage mutation.

mutation sendEmail ($input:SendMessageInput!) {
  sendMessage(
    input: $input
  ) {
    id
  }
}

{
  "input": {
    "to": { "name": "Max Mustermann", "address": "email@example.org" },
  	"subject": "YOUR_EMAIL_SUBJECT",
    "from": {"name":"Max Mustermann", "address": "YOUR_VERIFIED_EMAIL"},
  	"textBody": "YOUR_EMAIL_BODY"    
  }
}

You can delete previously created email verification 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.

Sending email from any email address of a custom domain

To send email using this approach, you must have access to the DNS records of the domain some.company and have that domain verified by SBS. This is a one-time process and it consists of the following steps:

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
      }
    }
  }
}

Once the status returns VERIFIED, you can start using the domain for sending email. More specifically, when running the sendMessage mutation, you can use any email address that belongs to the verified domain in the email’s from field, for example:

mutation sendEmail ($input:SendMessageInput!) {
  sendMessage(
    input: $input
  ) {
    id
  }
}

{
  "input": {
    "to": { "name": "TO_NAME", "address": "TO_EMAIL" },
  	"subject": "Test email",
    "from": {"address":"ANY.ADDRESS@YOUR.VERIFIED.DOMAIN"},
    "htmlBody": "<div>This is some <strong>HTML</strong>.</div>"
  }
}

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

Sending email from a Google or Microsoft 365 email address

To send email from an email address managed by Google or Microsoft 365®, you must connect the user’s mail inbox to SBS, using one of the following approaches:

1. App Password
2. OAuth access token

App Password

To send email from an email address authorized by App Password, your app must collect from the user their third-party email address (managed by Google or Microsoft) and their corresponding app password. For instructions about obtaining an app password, see Obtaining a Google App Password and Obtaining a Microsoft 365 App Password.

Once you have the user’s email address and an app password, you can send messages by calling sendMessage as follows (this example assumes the app password was obtained for a Google email address):

mutation sendEmail ($input:SendMessageInput!) {
  sendMessage(
    input: $input
  ) {
    id
  }
}

{
  "input": {
    "to": { "address": "TO_EMAIL" },
  	"subject": "Test sending email with Google app password",
    "from": {
      "address":"YOUR_GOOGLE_EMAIL_ADDRESS",
      "appPassword": {
          "password": "YOUR_GOOGLE_APP_PASSWORD",
          "provider": "GOOGLE"
      }
    },
    "htmlBody": "<div>This is some <strong>HTML</strong>.</div>"
  }
}

Optionally, you can store the email and app password as a verified identity in SBS. Doing this would enable you to call sendMessage without supplying the app password as input, for example:

{
  "input": {
    "to": { "address": "TO_EMAIL" },
  	"subject": "Test sending email with Google app password",
    "from": {
      "address":"YOUR_GOOGLE_EMAIL_ADDRESS",
    },
    "htmlBody": "<div>This is some <strong>HTML</strong>.</div>"
  }
}

To store a verified Google or Microsoft identity in SBS, run the addEmailAccount mutation, for example:

mutation addEmailAccount($input:AddEmailAccountInput!) {
  addEmailAccount(input:$input) {
    id
    address
    provider
  }
}

{
  "input": {
    "address": "YOUR_EMAIL_ADDRESS",
    "password": "YOUR_GOOGLE_APP_PASSWORD",
    "provider": "GOOGLE"
  }
}

To list the previously added third-party email accounts, run the emailAccounts query.

To update or delete third-party email accounts, run the updateEmailAccount and deleteEmailAccount mutations, respectively.

OAuth Access Token

To send email from an email address authorized by OAuth 2.0 Access Token:

1. Perform an authorization of the user as described in Authorization through OAuth 2.0. As part of this step, you will need to provide an approver identifier, which must be set to the internal id of the user in your application.
2. Run the sendMessage mutation of the Email Service, for example:

mutation sendEmail ($input:SendMessageInput!) {
  sendMessage(
    input: $input
  ) {
    id
  }
}

In variables, make sure to replace values as required. Note that the oauthApprover must be set to the approver ID used in step 1.

{
  "input": {
    "to": { "name": "Max Mustermann", "address": "email@example.org" },
  	"subject": "YOUR_EMAIL_SUBJECT",
    "from": {"oauthApprover": "USER_ID" },
  	"textBody": "YOUR_EMAIL_BODY"    
  }
}

You can list the previously obtained OAuth 2.0 authorizations by running the authorizations query of the OAuth Service.

Viewing the delivery status

You can view the delivery status of sent email, by running the messages query and requesting the status of each TO, CC, or BCC recipient, for example:

query sent ($filter:MessagesFilter, $nextToken:String) {
  messages(filter:$filter, nextToken:$nextToken) {
    items {
        id
        to { name address status }
        cc { name address status }
        bcc { name address status }
        subject
        sentAt
    }
    nextToken
  }
}

Note that the delivery status cannot be tracked if the email was sent from a Google or Microsoft account authorized through OAuth 2.0 or app password.

Sending email with tracking options

When sending email, you can optionally enable tracking options. With tracking options are enabled, you can view the following statistics for a sent email message:

• whether the message was opened by the recipient, and how many times. For each open event, you can view the origin IP address, and the time when the open event took place.
• whether any links within the email were clicked, and how many clicks took place in total. For each click event, you can view the link that was opened, the origin IP address and the time when the event took place.

You can set tracking options only for email sent through the following means:

• from the default address
• from a custom verified email address
• from a custom verified domain

It is not possible to set tracking options for email sent from Google or Microsoft addresses that were verified by either OAuth 2.0 authorization or app password.

Tracking options are not enabled by default. To enable tracking options, set the trackEngagement input parameter to true and make sure that the email is in HTML format, for example:

mutation sendMessage ($input:SendMessageInput!) {
  sendMessage(
    input: $input
  ) {
    id
    subject
    messageId
    htmlBody
  }
}

{
    "input": {
        "to": {
            "address": "SOME_EMAIL_ADDRESS"
        },
        "subject": "Lorem ipsum",
        "htmlBody": "<body><p>This is a <a href=\"https://socrate.io\">link</a>.</p></body>",
        "trackEngagement": true
    }
}

When tracking is enabled, a tiny 1 pixel image is embedded within the HTML body of the sent message. In addition, all links within the email body are transformed to include Amazon Web Services tracking code.

Note that, if the recipient’s email client application is configured to block images from incoming emails, the tracking statistics will not be available until the user chooses to display the images.

To view the tracking statistics, run the messages query and request statistics about the “open” and “click” events, for example:

query sent ($filter:MessagesFilter, $nextToken:String) {
  messages(filter:$filter, nextToken:$nextToken) {
    items {
        id
        messageId
        from { address, name }
        replyTo { name, address }
        to { address, status }
        subject
        openCount
        clickCount
        opens { createdAt, ipAddress, userAgent, timestamp }
        clicks { createdAt, link, ipAddress, userAgent, timestamp }
    }
    nextToken
  }
}

{
    "filter": {
        "ids": ["YOUR_EMAIL_ID"]
    }
}

Receiving email

You can configure SBS to accept email at any address that has the following format:

 {recipient}@{tenant_subdomain}.{app_subdomain}.socrate.email

where {recipient}, {tenant_subdomain}, and {app_subdomain} are the configurable parts. Note the following:

• recipient can be virtually any string. For example, you could use as recipient a department name (such as “sales”, “accounting”, etc), or even include ticket numbers (“support-case-5678654”).
• tenant_subdomain is the part that identifies the tenant in the SBS system.
• app_subdomain is the part that identifies the app in the SBS system.

To configure your application for receiving email:

1. Register an email subdomain for your application. You can do this from the SBS Console, by running the registerAppSubdomain mutation of the Account API. For instructions, see Register an email subdomain.
2. Register a subdomain for your tenant. This string must be unique for each tenant if there are multiple tenants using the same app. 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"
  }
}

You can now view the currently registered app and tenant subdomain, by running the subdomain query:

query subdomain {
  subdomain {
    domain
    subdomain
  }
}

The result is similar to the following:

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

In the code listing above, the tenant subdomain is sub and the app subdomain is app. Therefore, any email sent to an address like recipient@sub.app.socrate.email will now reach your app. You can list all received emails with the InboundMessages query.

Queries

addressStatus

Returns information about whether the email address supplied as input is in the AWS Suppression List, and the reason why. To remove an email address from the suppression list, run the unsuppressAddress mutation.

Arguments

Result

AddressStatus type

domainIdentities

Returns a list of email domain identities and their verification status (verified or pending verification). Only email from verified domains can be used when sending email from any email address of a custom domain.

Arguments

DomainIdentitiesFilter type

Result

DomainIdentitiesResult type

DomainIdentity type

DnsRecord type

emailAccounts

Returns a list of email accounts authorized to send email managed by providers such as Google or Microsoft 365.

Arguments

EmailAccountsFilter type

Result

emailAccountsResult type

emailAccount type

emailIdentities

Returns a list of email verification requests and their outcome (verified or pending verification), also referred to as “email identities”. Only verified email identities can be used in the from field when sending email from a custom email address.

Arguments

EmailIdentitiesFilter type

Result

EmailIdentitiesResult type

EmailIdentity type

inboundMessages

Returns a list of received email messages, filtered according to the provided criteria. You can provide the criteria through the filter argument.

Arguments

InboundMessagesFilter input

This object provides the criteria by which email messages should be filtered. Note that, if you specify multiple criteria, they will be joined with a logical AND (that is, the call will return only messages that satisfy all criteria).

Result

InboundMessagesResult type

InboundMessage type

File type

messages

Returns a list of sent email messages, filtered according to the provided criteria. You can provide the criteria through the filter argument.

Arguments

MessagesFilter input

This object provides the criteria by which email messages should be filtered. Note that, if you specify multiple criteria, they will be joined with an AND logical clause (that is, the call will return only messages that satisfy all criteria).

DateFilter input

Result

MessagesResult type

Message type

ContactUser type

Contact type

Recipient type

Attachment type

Open type

Click type

subdomain

Returns the currently configured email domain and subdomain, if any. Subdomain configuration is required to receive email messages.

Result

Subdomain type

Returns the currently configured email subdomain. This is a string that identifies the tenant, see Receiving email.

version

Returns the API version.

Mutations

addEmailAccount

This mutation is useful if you would like to allow your app’s users to connect an email account from a third-party provider (such as Google or Microsoft 365) to the app through an app password. The app password itself must be obtained by the user from the third-party provider. For details, see Obtaining a Google App Password and Obtaining a Microsoft 365 App Password.

The addEmailAccount mutation adds to SBS the email account managed by Google or Microsoft 365 and stores the app password associated with that email account. Once added, the email address can be used in the from field when sending email through the sendMessage mutation.

Storing the app password in SBS is optional. The alternative is to supply the app password as input in the from field when sending email through the sendMessage mutation.

Arguments

AddEmailAccountInput input

Result

See the EmailAccount type.

deleteEmailAccount

This mutation deletes a previously added email account from a third-party provider (such as Google or Microsoft 365).

Arguments

Result

See the EmailAccount type.

deleteDomainIdentity

Deletes a domain identity. Domain identities are created by running the verifyDomainIdentity mutation.

Arguments

Result

See the DomainIdentity type.

deleteEmailIdentity

Deletes an email identity. Email identities are created by running the verifyEmailIdentity mutation.

Arguments

Result

See the EmailIdentity type.

deleteSubdomain

Deletes a previously registered email subdomain, see Receiving email.

Arguments

DeleteSubdomainInput input

Result

See the Subdomain type.

registerSubdomain

Register an email subdomain that uniquely identifies the current tenant within this app. For more information, see Receiving email.

Arguments

RegisterSubdomainInput input

Result

See the Subdomain type.

sendMessage

Sends an email message to the specified recipients.

Arguments

SendMessageInput input

ContactInput input

ContactUserInput input

AttachmentInput input

TemplateInput input

AppPasswordInput input

unsuppressAddress

Removes an email address from the AWS suppression list.

Arguments

Result

See the AddressStatus type.

updateEmailAccount

This mutation updates a previously added email account from a third-party provider (such as Google or Microsoft 365).

Arguments

UpdateEmailAccountInput input

Result

See the EmailAccount type.

updateInboundMessage

Updates a received (inbound) email message. Note that the only updatable field is externalReference.

Arguments

UpdateInboundMessageInput input

Result

See the InboundMessage type.

verifyDomainIdentity

Performs a verification of a custom email domain. Email domain verification is a prerequisite to enable sending email from any email address of a custom domain.

Arguments

Result

See the DomainIdentity type.

verifyEmailIdentity

Performs a verification of a custom email address. Email address verification is a prerequisite to enable sending email from a custom email address.

Arguments

Result

See the EmailIdentity type.