Stax requires an email address template to be specified as part of onboarding new and existing AWS organizations.
This template is used when determining the email addresses for AWS accounts Stax creates. The email address template must provide room for a Stax-generated account identifier in the format of a UUID. See Why must the UUID be used? below for more information on the UUID.
The email address template provided should also exist within your organization and be monitored to ensure that emails dispatched to these addresses can be acted upon as appropriate. Typically, a shared mailbox or distribution group is utilized for this purpose.
The recommended email address format is aws+${Stax::AccountId}@example.com. This would result in AWS accounts being created with email addresses such as aws+7e196280-1157-45e3-824a-9f6aef9946b8@example.com.
Placeholders
The following placeholders can be used as part of the email address template. One of either ${Stax::AccountId} or ${Stax::ShortAccountId} must be present in the template.
| Placeholder | Description | Example |
|---|---|---|
| ${Stax::AccountId} | The Stax-generated UUID for the AWS account | 7e196280-1157-45e3-824a-9f6aef9946b8 |
| ${Stax::ShortAccountId} |
The Stax-generated UUID for the AWS account, without the separating hyphens. This saves four characters but reduces readability | 7e196280115745e3824a9f6aef9946b8 |
| ${Stax::StaxOrgAlias} | Optional. The organization ID of the account's Stax tenancy | your-company |
Considerations
When determining the template for your organization, consider the following limitations:
- AWS limits the maximum length of these email addresses to 64 characters
- The UUID generated by Stax has a length of 36 characters, leaving 28 characters for other parts of the email address
- The UUID generated by Stax will not be known ahead of time, so using something like the convention of SMTP subaddressing supported by many vendors is encouraged (Microsoft 365, Gmail). See Understanding Subaddressing below for more information
- AWS account number is unable to be used in the email address template because the email address must exist before the account can be created
Why Must the UUID Be Used?
When an AWS account is created, a unique email address must be provided to AWS for the account's root user credential. As the AWS account ID is not determined until the account creation process is undertaken, Stax is unable to pre-emptively enter the AWS account ID into the email address template, and must instead use its UUID identifier for the account, which is generated ahead of time.
Change Email Address Format
Changing the email address format of your AWS Accounts is a manual process, so it's recommended to carefully consider the format when commencing the Stax provisioning process.
If the email address format is to be changed after your Stax tenancy is first provisioned, several steps must be completed:
- Inform Stax (via a support case) of the new email address format. The support team will update the format so that any new accounts provisioned within your Stax tenancy will use this format.
- Update each AWS account's email address. You will need to access each AWS account's root user credential and change the email address to the new format.
When implementing a new format, ensure it meets all details covered in the considerations above.
Understanding Subaddressing
Subaddressing is a technique in email addressing that allows one mailbox to have an effectively unlimited number of email addresses associated with it, given a prescribed prefix. An example of this is used in this document where the mailbox aws@example.com has subaddressing utilized to allow it to receive email for many AWS accounts, each of which requires a unique email address.
Subaddressing, in most circumstances, uses a plus sign (+) to allow users to add an arbitrary detail to an email address. In this example, aws@example.com, aws+something@example.com, and aws+467cba57-04f2-439a-89d6-9b63ae79c470@example.com would all result in mail being delivered to the aws@example.com mailbox.
This technique can be used when Stax creates AWS accounts on your behalf. By placing the account's UUID after a plus sign, for a suitably capable mail system, email for all AWS accounts can be delivered to one central mailbox or distribution group.