Configure an email-sending domain

There are certain business cases where all tenants linked to a particular application need the ability to send email from the same email address. For example, let’s imagine that Tenant A and Tenant B are both linked (through their service access key) to an app called “Example.app” and both need to send auto-generated mail from an address like no.reply@example.org).

To make the scenario above possible, the email domain example.org must be configured at application level, which is the subject of this topic.

Configuration

To configure an email domain at application level, there are two steps:

1. Verify that domain at application level.
2. Add one or multiple authorized email senders for that domain.

Step 1: Verify the email domain

To verify a domain identity at application level:

1. Run the verifyDomainIdentity mutation of the Account API and provide the ID of your application and the name of the domain to be verified as input arguments.

mutation verifyDomainIdentity($appId:ID!, $domain:Domain!) {
  verifyDomainIdentity(appId:$appId, domain:$domain) {
    domain
    status
    dnsRecords { type name value }
  }
}

{
    "appId": "YOUR_APP_ID",
    "domain": "example.org"
}

2. In the response, you will get a list of ten DNS records. Add to your domain’s DNS records the ten new DNS records received previously.

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

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

query app($id:ID!,$domainIdentitiesFilter:DomainIdentitiesFilter){
  app(id:$id){
    id
    name
    domainIdentities(filter: $domainIdentitiesFilter) { domain status }
    emailSenders
  }
}

{
    "appId": "YOUR_APP_ID"
}

Step 2: Add email senders

Email senders are email addresses authorized to send email at application level for a designated domain. Notice that the domain of each email address must be the same as the domain verified previously. For example, if you verified a domain like example.org in Step 1, you should one or more email senders for that domain, for example jane.doe@example.org, john.doe@example.org, and so on.

To add an authorized email sender, run the addEmailSender mutation of Account API, for example:

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

{
    "appId": "YOUR_APP_ID",
    "address": "jane.doe@example.org"
}

To view the email senders configured for a particular app, run the app query and request the emailSenders response field, for example:

query app($id:ID!,$domainIdentitiesFilter:DomainIdentitiesFilter){
  app(id:$id){
    id
    name
    domainIdentities(filter: $domainIdentitiesFilter) { domain status }
    emailSenders
  }
}

{
    "appId": "YOUR_APP_ID"
}

Maintenance

Delete a domain identity

To delete a domain identity (either VERIFIED or PENDING), run the deleteDomainIdentity mutation of the Account API, for example:

mutation DeleteDomainIdentity($appId:ID!,$domain:Domain!) {
  deleteDomainIdentity(appId:$appId, domain:$domain) {
    domain
    status
    dnsRecords { type name value }
  }
}

{
    "appId": "YOUR_APP_ID",
    "domain": "example.org"
}

Delete an email sender

To delete an email sender, run the removeEmailSender mutation of the Account API, for example:

mutation RemoveEmailSender($appId:ID!,$address:EmailAddress!) {
 removeEmailSender(appId:$appId,address:$address) 
}

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