Email Service

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

• From any email address of a custom domain that you verify. For example, if your domain is example.org, then you can configure it such that laura@example.org, bob@example.org, etc., can send email from that domain. This approach is typically useful for organizations with multiple domains and multiple users across each domain. It uses domain verification and provides a robust delivery mechanism. This is the recommended approach for production-grade applications. You can choose to configure your domains either at application level (and allow all tenants linked to the respective app to send email from that domain), or at the individual tenant level only. For more information, see Configure an email-sending domain at application level and see Sending email from a domain verified at tenant level.
• 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. This approach is suitable for organizations where email addresses are managed through a Google Workspace (formerly G suite) or Microsoft 365® subscription. For more information, see Sending email from a Google or Microsoft 365® email address.
• From a custom email address such as sales@some.company. This approach does not use domain verification, so it is typically suitable for testing and development, or in internal applications where the email senders are known to the recipient. You can configure the email sending address either at application level (and allow all tenants linked to the application to send email from that address), or at the individual tenant level only. For more information, see Sending email from a custom email address and Verify an email identity at application level.
• From the default email address no-reply@socrate.email. This approach is for testing and development purposes only. For more information, see Sending email from the default email address.

When sending email with attachments, you can use as attachments any files created previously through createAttachmentFile.

To parameterize the email content or format your emails using HTML/CSS, you can optionally use 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.

To investigate delivery problems across all of your sent messages, run the deliveryFailures query. It returns the history of email addresses that bounced or reported the message as spam, together with the reason and the time of each failure.

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.

Access info

Usage

Sending email from a domain verified at tenant level

You can designate a specific custom domain to be used for sending email, by verifying it. For example, if your domain is example.org and it is verified, then designated email addresses on that domain (such as marketing@example.org, support@example.org, and so on) can send email from the respective domain.

To configure your domain for sending email:

1. Verify the domain at tenant level.
2. Restrict sending email only to specific email addresses on that domain. This is an optional, but recommended, step. If you enforce this restriction, sending email will be possible only if the domain is verified and if the email address is in the list of authorized senders. If you do not enforce this restriction, any email address from the domain can send email as long as the domain is verified.
3. Optionally, configure the Sender Policy Framework (SPF) for your domain.

You can perform the configuration either through GraphQL as described below, or through a graphical user interface (SBS Portal). For instructions about the latter, see Authorized email senders.

Step 1: Verify the domain

1. Run the verifyDomainIdentity mutation. In the example below, sending email from the domain will be possible only for designated email addresses, because we explicitly set the optional parameter restrictedToEmailSenders to true. The authorized email addresses will be added in a subsequent step.

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

{ 
    "domain": "YOUR_DOMAIN",
    "input": {
        "restrictedToEmailSenders": true
    }
}

2. In the response, you will get a list of four DNS records.

3. Add the DNS records given above to your domain’s DNS zone. The instructions for adding the new DNS records will vary depending on your domain provider.

To view the domain identity and its verification status, run the domainIdentities query, for example:

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

Step 2: Add the authorized senders

In Step 1, we have specified that only designated email addresses are allowed to send email from this domain, by setting the restrictedToEmailSenders option to true. Let’s now add the email addresses authorized to send email for the designated domain, for example:

mutation AddEmailSender($address:EmailAddress!) {
  addEmailSender(address:$address)
}

{
    "address": "jane.doe@example.org"
}

To view the current email senders, run the emailSenders query, for example:

query EmailSenders {
  emailSenders
}

Step 3 (optional): Configure Sender Policy Framework (SPF)

Optionally, to improve the email delivery rate, it is recommended that you add or modify your domain’s Sender Policy Framework. This helps the servers to which you send email verify that your domain is authentic.

More specifically, there is a DNS record of type “TXT” which may already exist on your domain in the form:

Since Socrate Email Service is built on top of Amazon Web Services, the record value must be modified to include amazonses.com as designated outbound mailer, for example:

For more information about Sender Policy Framework, see:

• RFC 7208: Sender Policy Framework (SPF) for Authorizing Use of Domains in Email, Version 1 (https://datatracker.ietf.org/doc/html/rfc7208)
• OpenSPF Project Documentation (http://www.open-spf.org/SPF_Record_Syntax/)

Using the email sender addresses

Once you’ve completed the steps above, you can start using the domain for sending email. More specifically, when running the sendMessage mutation, you can use any verified email sender address 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":"AUTHORIZED.SENDER@YOUR.VERIFIED.DOMAIN"},
    "htmlBody": "<div>This is some <strong>HTML</strong>.</div>"
  }
}

If you haven’t enabled the restrictedToEmailSenders option on the domain, then you can use any email address of that domain in the from field.

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, do one of the following:

• Sign in to the SBS Portal and store your app password.
• 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.

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 at application level.
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.

To verify an email identity at tenant level:

1. Run the verifyEmailIdentity mutation and supply the email address to be validated as input. As a result, you will receive two 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 emails, 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"    
  }
}

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 an example, see Tutorial: Send an email.

Sending email with attachments

To send email with attachments, you have to create the attachment files first by running the createAttachmentFile mutation (this is the recommended approach). Alternatively, you can use as attachment any file from the File Management Service.

Once you have the ID(s) of the file attachment(s), you can supply them as parameters when sending the email, for example:

mutation sendMessage ($input:SendMessageInput!) {
  sendMessage(
    input: $input
  ) {
    id
    subject
    messageId
    htmlBody
    textBody
    attachmentCount
    attachments { name fileId }
  }
}

{
  "input": {
   	"to": [{ "address": "{{SOME_EMAIL_ADDRESS}}" }],
  	"subject": "Example email sent with file attachments",
    "htmlBody": "<body><p>This is a test with a PDF file attachment<p>Sent by SBS</p></body>",
    "attachments": [
        {
            "fileId": "{{YOUR_FILE_ID1}}"
        },
        {
            "fileId": "{{YOUR_FILE_ID2}}"
        }
    ]
   }   
  }

In the code listing above, replace YOUR_FILE_ID1 and YOUR_FILE_ID2 with any file ID created through createAttachmentFile or any file ID from the File Management Service.

Sending email using a template

When sending an email, you can optionally apply a template and supply parameters for rendering the respective template. This is useful to send email messages where certain text (for example, URLs or user names) should be supplied dynamically from external sources. You can create templates either from the Document Rendering UI of the SBS Portal, or by calling the Document Rendering Service programmatically.

The following GraphQL code illustrates creating an email template by calling the Document Rendering Service. Notice that the url, name, and code are parameter placeholders:

mutation createTemplate ($input:CreateTemplateInput!) {
        createTemplate(input:$input) {
          id
          name
        }
}

{
    "input": {
        "name": "demo-template",
        "type": "email",
        "subject": "Your activation code for {{url}}",
        "body": "Hello, {{name}}!\n\nHere is the activation code to complete your registration:\n\n{{code}}\n\nSincerely,\nTeam",
        "contentType": "plain"
    }
}

The following code listing illustrates sending an email by applying the demo-template template defined earlier:

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

{
  "input": {
	"to": [{ "address": "somebody@example.org" }],
  	"template": {
          "name": "demo-template",
          "params": "{\"url\": \"https://example.org\", \"name\": \"John Doe\", \"code\": \"123456\"}"
      }
   }
  }

Since the API call uses a template, the email above will reach the destination address in the form:

**Subject:** Your activation code for https://example.org

**Body:** Hello, John Doe!

Here is the activation code to complete your registration:

123456

Sincerely,
Team

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.

Viewing the delivery failure history

While the messages query tells you the delivery status of a specific message, the deliveryFailures query returns the recorded history of all failed deliveries for your tenant, starting with the most recent one. Use it to investigate delivery problems across messages, rather than one address or one message at a time. For each failure, you obtain the recipient address, the type of failure, the reason reported for it, the time when it occurred, and the identifier of the message that failed, for example:

query deliveryFailures ($filter:DeliveryFailuresFilter, $nextToken:String) {
  deliveryFailures(filter:$filter, nextToken:$nextToken) {
    items {
        emailAddress
        timestamp
        failureType
        reason
        messageId
    }
    nextToken
  }
}

To restrict the results to a period of time, provide a date range in the timestamp filter:

{
    "filter": {
        "timestamp": {
            "from": "2026-07-01",
            "to": "2026-07-31"
        }
    }
}

To find out whether a specific email address is currently blocked for delivery, run the addressStatus query instead. To unblock it, run the unsuppressAddress mutation.

Sending email with tracking options

When sending email, you can optionally enable tracking options. When 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

SBS will accept email at any address that has the following format:

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

where:

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

To configure your application for receiving email:

1. Register an email subdomain for your application. You can do this from the SBS Console, or by running the registerAppSubdomain mutation of the Account API. For instructions, see Register an email subdomain at application level.
2. Register a subdomain for your tenant. You can do this from the SBS Portal, or by running the registerSubdomain mutation of the Email Service. For instructions, see Register an email subdomain at tenant level.

To query all received email, run 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.

This query reports only the current suppression state of a single address. To obtain the history of all delivery failures recorded for your tenant, run the deliveryFailures query.

Arguments

Result

AddressStatus type

deliveryFailures

Returns the history of email delivery failures recorded for your tenant, in reverse-chronological order (the most recent failure first). A failure is recorded when a message did not reach the recipient, or when the recipient marked it as Spam or Junk. You can restrict the results to a period of time through the filter argument.

Arguments

DeliveryFailuresFilter input

Result

DeliveryFailuresResult type

DeliveryFailure type

domainIdentities

Returns a list of email domain identities and their verification status (verified or pending verification). You should create and verify a domain identity if you intend to send email from a domain verified at tenant level.

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

emailSenders

Returns a list of email addresses authorized to send email from the configured domain identities.

Arguments

None.

Result

The result is an array of EmailAddress.

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 information about the currently configured inbound email domain. More precisely, the result is an object that contains three attributes:

• appLevelDomain - the email domain configured at application level. For example, if your app is configured to receive all inbound email at @ten.app.socrate.email, then appLevelDomain is “app.socrate.email”.
• subdomain - the email subdomain configured at tenant level. For example, if your app is configured to receive all inbound email at @ten.app.socrate.email, then subdomain is “ten”.
• domain - the full email domain at which your app is configured to receive all inbound email. It consists of subdomain, followed by a dot, followed by appLevelDomain. Both appLevelDomain and subdomain must be defined in order for domain to be considered configured. A null value means the inbound email domain is not configured.

For instructions about configuring the inbound email domain, see Receiving email.

Result

Subdomain type

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.

addEmailSender

Adds an email address authorized to send email from any of the configured domain identities.

Arguments

Result

The result is an EmailAddress type.

Example

mutation AddEmailSender($address:EmailAddress!) {
  addEmailSender(address:$address)
}

{
  "address": "authorized.sender@example.org"
}

createAttachmentFile

Creates a file to be used as an email attachment.

Arguments

CreateAttachmentFileInput input

Result

AttachmentFile type

Example

Creating attachment files is a two-step operation. First, run the createAttachmentFile mutation and specify the file name to be created as input, for example:

mutation CreateAttachmentFile($input:CreateAttachmentFileInput!) {
  createAttachmentFile(input: $input) {
    id
    uploadUrl(expiresIn:3600)
  }
}

{
    "input": {
        "name": "test.pdf",
        "contentType": "application/pdf",
    }
}

The mutation above creates a file and returns the file’s upload URL. The latter is required for the next step. Note that the period after which the upload URL will expire can be parameterized according to your needs. In the mutation above, it is 3600 seconds (1 hour).

Secondly, run an HTTP PUT request and upload the actual file bytes to the upload URL. The exact program code to achieve this depends on the language you are using. With cURL, the upload operation looks as follows:

• If you have a bash terminal, run:
  Copy

  curl --location --request PUT 'YOUR_UPLOAD_URL' --header 'Content-Type: application/pdf' --data-binary '@/path/to/your/file.pdf'
  

• If you have a Windows terminal, run:
  Copy

  curl --location --request PUT "YOUR_UPLOAD_URL" --header "Content-Type: application/pdf" --data-binary "@C:\file.pdf"
  

You can query the created attachment files from the File Management Service, by ID. The ID of the file in both services is the same.

deleteDomainIdentity

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

Arguments

Result

See the DomainIdentity 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.

deleteEmailIdentity

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

Arguments

Result

See the EmailIdentity type.

deleteInboundMessage

Deletes an inbound email and its attachments.

Arguments

Result

See the InboundMessage type.

Example

mutation deleteInboundMessage($id:ID!) {
        deleteInboundMessage(id:$id) {
          id
          messageId
          from { address, name }
          to { address, status}
          subject
        }
      }

{
    "id": "YOUR_EMAIL_ID"
}

deleteMessage

Deletes a sent email.

Arguments

Result

See the Message type.

Example

mutation DeleteMessage ($id:ID!) {
  deleteMessage(
    id: $id
  ) {
    id
    messageId
    from { name address oauthApprover }
    subject
  }
}

{
    "id": "YOUR_EMAIL_ID"
}

deleteSubdomain

Deletes a previously registered email subdomain, see Receiving email.

Arguments

DeleteSubdomainInput input

Result

See the Subdomain type.

removeEmailSender

Removes an email address from the list of senders authorized to send email from any of the configured domain identities.

Arguments

Result

The result is an EmailAddress 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 a domain verified at tenant level.

Arguments

VerifyDomainIdentityInput input

Result

See the DomainIdentity type.

Example

The example below illustrates how to verify a domain. Make sure to replace YOUR_DOMAIN with the actual domain name, for example, example.org. In this example, sending email from the domain will be possible only for designated email addresses, because the restrictedToEmailSenders parameter is set to true. You can add the authorized email addresses by running the addEmailSender mutation.

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

{ 
    "domain": "YOUR_DOMAIN",
    "input": {
        "restrictedToEmailSenders": true
    }
}

updateDomainIdentity

Updates a domain identity.

Arguments

UpdateDomainIdentityInput input

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.

Error codes

See Conventions for the error format and the codes shared across all services. This service can also return the codes listed below, grouped by the object they concern. The Returned by column names the operations that report each code.

Messages

Attachments

Senders and identities

Google and Microsoft 365 accounts

Subdomains and applications

Suppression list

Email address values

AI agent access (MCP)

The service serves its queries as tools to AI agent clients over the Model Context Protocol (MCP), a JSON-RPC 2.0 protocol through which a client reads a catalog of tools and calls them by name. Agent clients such as Claude Code connect to https://email-api.socrate.io/mcp.

Access

The MCP endpoint is on the same host as the GraphQL endpoint and accepts the same credentials:

• A tenant-level service access key, in the x-api-key header.
• A service access token, in the Authorization header as Bearer YOUR_SERVICE_ACCESS_TOKEN.

The endpoint speaks protocol revision 2026-07-28 and accepts protocol requests as POST only. It is stateless: every request carries its own credentials, and there is no handshake or session to open first. Your agent client must support revision 2026-07-28.

For connection instructions, open https://email-api.socrate.io/mcp in a browser. The page needs no credential.

Tools

The catalog holds one tool per query of this service:

No tool has a required argument. The optional arguments of each query (filter, nextToken, order, address) are optional arguments of its tool. The tools cover the service’s queries only. To send messages or to create or change data, use the service’s mutations.

The catalog a caller receives lists only the tools whose query the scope of its key or token allows. If a service access denial blocks a query, your agent does not see a tool for it. A tool call runs the query under the caller’s own credentials and returns the data that the equivalent GraphQL query returns for that caller. Every tool is marked read-only (readOnlyHint is true), and answers from SBS alone, without calling any system outside SBS (openWorldHint is false).

Optional result fields

By default, a tool returns compact records. You request the remaining fields by naming their paths in the tool’s optional include argument:

• Sent messages. Without include, messages returns each message’s own fields, such as id, from, subject, sentAt, attachmentCount, openCount, and clickCount. The text and HTML bodies, the recipients, the attachments, the opens, the clicks, and the references are returned only when named.
• Inbound messages. Without include, inboundMessages returns each message’s own fields and its original file without a download URL. The text and HTML bodies, the recipients, the attachments, the references, and the download URL of the original file are returned only when named.
• Domain identities. Without include, domainIdentities returns each identity’s domain, status, and restrictedToEmailSenders. The DNS records are returned only when named.

Each of these tools always returns its page of items and its nextToken.

A path is a sequence of field names separated by dots. Naming a path returns that field with its default content. Naming a path inside a field that is returned by default adds only that inner field: include: ["items.original.downloadUrl"] adds the downloadUrl of each message’s original beside its id, contentType, and contentLength. To receive several optional fields, name each path: include: ["items.to", "items.textBody"].

Sent message include values

The messages tool accepts these values:

Inbound message include values

The inboundMessages tool accepts these values:

Documentation resources

Besides its tools, the endpoint publishes, as addresses, this page and the API conventions page.

Connecting an agent client

To add the endpoint to Claude Code, run:

claude mcp add --transport http email https://email-api.socrate.io/mcp --header "x-api-key: YOUR_ACCESS_KEY"

Other agent clients take the same URL and header in their own configuration.

Example

An agent client builds the protocol requests for you. To call a tool directly over HTTP, send a POST request that names the protocol revision both in the MCP-Protocol-Version header and in the request’s _meta, the method in the Mcp-Method header, and, for a tool call, the tool in the Mcp-Name header:

POST /mcp HTTP/1.1
Host: email-api.socrate.io
Content-Type: application/json
Accept: application/json
x-api-key: YOUR_ACCESS_KEY
MCP-Protocol-Version: 2026-07-28
Mcp-Method: tools/call
Mcp-Name: messages

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "_meta": {
      "io.modelcontextprotocol/protocolVersion": "2026-07-28",
      "io.modelcontextprotocol/clientCapabilities": {}
    },
    "name": "messages",
    "arguments": {
      "filter": {
        "createdAt": { "from": "2026-10-01", "to": "2026-10-31" }
      },
      "include": ["items.to"]
    }
  }
}

The page of messages is returned in structuredContent, and as the same JSON text in content. The response below is shortened to one message:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "resultType": "complete",
    "content": [
      { "type": "text", "text": "{\"items\":[{\"id\":\"YOUR_MESSAGE_ID\", ...}" }
    ],
    "structuredContent": {
      "items": [
        {
          "id": "YOUR_MESSAGE_ID",
          "from": {
            "name": "Contoso Sales",
            "address": "sales@example.com"
          },
          "subject": "Your order has shipped",
          "to": [
            {
              "name": "Jane Doe",
              "address": "jane.doe@example.com",
              "status": "DELIVERED"
            }
          ],
          "createdAt": "2026-10-07T06:08:56.352Z",
          "sentAt": "2026-10-07T06:08:57.104Z",
          "attachmentCount": 0,
          "openCount": 1,
          "clickCount": 0
        }
      ],
      "nextToken": "YOUR_NEXT_TOKEN"
    }
  }
}

Webhooks

The Email Service supports webhooks. This means you can optionally configure SBS to send an HTTP POST request to an external server or application whenever any of the following events occur:

• EMAIL_RECEIVED - fires whenever an email was received.
• EMAIL_DELIVERED - fires whenever an email was delivered.
• EMAIL_DELIVERY_FAILURE - fires whenever an email has failed delivery.

The POST request of the EMAIL_RECEIVED event has the following payload:

{
  "service": "email-api",
  "event": "EMAIL_RECEIVED",
  "tenantId": "<some-tenant-id>",
  "payload": {
      "id": "<some-email-id>",
      "address": "<some-email-address>"
  },
  "customKey1": "Custom value 1",
  "customKey2": "Custom value 2 "
}

The POST request of the EMAIL_DELIVERED event has the following payload:

{
  "service": "email-api",
  "event": "EMAIL_DELIVERED",
  "tenantId": "<some-tenant-id>",
  "payload": {
      "id": "<some-email-id>",
      "address": "<some-email-address>"
  },
  "customKey1": "Custom value 1",
  "customKey2": "Custom value 2 "
}

The POST request of the EMAIL_DELIVERY_FAILURE event has the following payload:

{
  "service": "email-api",
  "event": "EMAIL_DELIVERY_FAILURE",
  "tenantId": "<some-tenant-id>",
  "payload": {
      "id": "<some-email-id>",
      "address": "<some-email-address>"
  },
  "customKey1": "Custom value 1",
  "customKey2": "Custom value 2",
}

Note that the customKey1 and customValue1 will be present in the request body only if you configured them when creating the webhook. You may configure as many key-value pairs as required.

For information about configuring webhooks, see Webhooks.