Tenants

This chapter explains how to use Amazon SES tenant management to isolate, monitor, and manage email sending across multiple tenants within your SES account. This feature helps Independent Software Vendors (ISVs), enterprises, and organizations sending emails on behalf of multiple downstream entities maintain separate reputation profiles and prevent issues with one tenant from affecting others.

What is tenant management?

Tenant management is a feature that allows you to create isolated containers called "tenants" within your SES account. Each tenant can have its own email identities, configuration sets, templates, and reputation metrics, ensuring that email activities are completely separated between different customers or business units.

Tenant management addresses the challenge where one customer's poor email practices could previously pause an entire SES account, affecting all other customers. With tenant isolation, you can manage multiple email streams independently while maintaining centralized oversight and control.

A tenant serves as a logical container that groups related SES resources together. When you send emails on behalf of a specific tenant, SES tracks reputation metrics, and enforces policies at the tenant level. This isolation ensures that a high bounce rate or complaint rate from one tenant doesn't impact the deliverability of emails sent by other tenants.

Tenant management is particularly valuable for:

How tenant management works

Tenant reputation management works by creating a logical container for your email sending resources. You assign specific resources to each tenant, including verified identities (domains and email addresses), configuration sets, and templates. When sending email on behalf of a tenant, you specify the tenant in your API call or SMTP header, and SES verifies that the resources being used are properly associated with that tenant.

Resource association

Resources in your SES account can be associated with tenants in two ways:

When you associate a resource with a tenant, that tenant gains permission to use that resource for email sending. With each send request, SES validates that the specified tenant has permission to use the identity, configuration set, and template in the request. If the resources aren't properly associated, the send request fails.

Reputation monitoring and enforcement

SES continuously monitors key reputation metrics for each tenant, including bounce rates, complaint rates (including those from the mailbox provider Feedback Loop (FBL) system), and third-party feedback signals. When these metrics exceed defined thresholds, SES creates "reputation findings" categorized as:

Based on these findings, SES can automatically pause problematic tenants through reputation policies that you configure. Three enforcement levels are available:

When a tenant's metrics trigger a reputation finding that meets the threshold for enforcement under your selected policy, the system automatically updates the tenant's sending status to "Paused" without affecting the sending capability of other tenants. While a tenant is paused, any attempt to send email using that tenant will fail until you review the issue and manually re-enable sending. Additionally, you can manually pause a tenant's sending capabilities when needed, and unpause it when ready to resume sending.

Setting up tenants

Creating tenants

Using the console:

Using the AWS CLI:

aws sesv2 create-tenant \
    --tenant-name "MyTenant" \
    --region us-east-1

Assigning resources to a tenant

After creating a tenant, you must assign at least one verified identity and one configuration set before the tenant can send email.

Using the console:

Using the AWS CLI:

# Assign an identity to a tenant
aws sesv2 create-tenant-resource-association \
    --tenant-name "MyTenant" \
    --resource-arn "arn:aws:ses:us-east-1:123456789012:identity/example.com" \
    --region us-east-1

# Assign a configuration set to a tenant
aws sesv2 create-tenant-resource-association \
    --tenant-name "MyTenant" \
    --resource-arn "arn:aws:ses:us-east-1:123456789012:configuration-set/MyConfigSet" \
    --region us-east-1

Configuring reputation policies

Reputation policies determine when a tenant's email sending is automatically paused based on reputation metrics. When you create a tenant, SES automatically assigns the Standard reputation policy. Use the following steps if you want to change to another policy.

Using the console:

Using the AWS CLI:

update-reputation-entity-policy \
    --reputation-entity-type "RESOURCE" \
    --reputation-entity-reference "arn:aws:ses:us-east-1:123456789012:tenant/tenantId" \
    --reputation-entity-policy "arn:aws:ses:us-east-1:aws:reputation-policy/standard"

Sending email with tenants

When sending email through a tenant, you must specify the tenant in your API calls or SMTP headers and ensure that all resources used are associated with that tenant.

Using the SendEmail API with tenants

AWS CLI Example:

aws sesv2 send-email \
  --tenant-name "MyTenant" \
  --from-email-address "sender@example.com" \
  --destination "ToAddresses=recipient@example.com" \
  --content "Simple={Subject={Data='Test Subject',Charset=utf-8},Body={Text={Data='Test email body',Charset=utf-8}}}" \
  --configuration-set-name "MyConfigSet"

AWS SDK for Python Example:

import boto3

client = boto3.client('sesv2')
response = client.send_email(
    FromEmailAddress='sender@example.com',
    Destination={
        'ToAddresses': ['recipient@example.com']
    },
    Content={
        'Simple': {
            'Subject': {
                'Data': 'Test email'
            },
            'Body': {
                'Text': {
                    'Data': 'This is a test email sent using a tenant.'
                }
            }
        }
    },
    ConfigurationSetName='MyConfigurationSet',
     TenantName='MyTenant'
)

Using SMTP with tenants

When using SMTP to send email through a tenant, include the tenant information in an email header:

X-SES-TENANT: MyTenant

This header tells SES which tenant should be used for the email sending operation, allowing SES to apply the appropriate resource validation and reputation tracking.

Managing tenant status

Viewing tenant status and metrics

Using the console:

Using the AWS CLI:

# Get tenant details
aws sesv2 get-tenant --tenant-name "MyTenant"

Pausing and unpausing tenants

You can manually pause a tenant's sending capabilities when needed, and unpause it when ready to resume sending.

Using the console:

Using the AWS CLI:

To pause a tenant:

# Pause a tenant
aws sesv2 update-reputation-entity-customer-managed-status \
  --reputation-entity-type RESOURCE 
  --reputation-entity-reference "arn:aws:ses:us-east-1:593442965613:tenant/tenantId"
  --sending-status DISABLED

To unpause a tenant:

# Unpause a tenant
aws sesv2 update-reputation-entity-customer-managed-status \
  --reputation-entity-type RESOURCE 
  --reputation-entity-reference "arn:aws:ses:us-east-1:593442965613:tenant/tenantId"
  --sending-status ENABLED

Working with reputation findings

Viewing reputation findings

Using the console:

Using the AWS CLI:

aws sesv2 list-recommendations \
   --filter='{ "RESOURCE_ARN":"arn:aws:ses:us-east-1:012345678901:tenant/tenantId"}'

The response includes details about all active findings:

{
    "Recommendations": [
        {
            "ResourceArn": "arn:aws:ses:us-east-1:012345678901:tenant/{tenant-name}/{tenant-id}",
            "Type": "BOUNCE",
            "Description": "The bounce rate exceeded 15.0% based on a representative volume of 664 emails from July 11, 2025 at 14:41 (UTC) to July 11, 2025 at 16:26 (UTC).",
            "Status": "OPEN",
            "CreatedTimestamp": "2025-07-11T16:16:14.029000+00:00",
            "LastUpdatedTimestamp": "2025-07-11T16:37:14.145000+00:00",
            "Impact": "HIGH"
        }
    ]
}

Understanding reputation findings

Reputation findings provide insights into potential issues with your tenants' email sending practices. Each finding includes:

Common findings include:

Resolving reputation issues

When you receive a reputation finding, it's important to investigate the root cause and take corrective action promptly:

Monitoring and analytics

Setting up CloudWatch metrics

SES publishes tenant-specific metrics to Amazon CloudWatch. The following metrics are available for each tenant:

Setting up EventBridge notifications

By default, SES sends events to the EventBridge default event bus when tenant reputation findings are detected or when tenant status changes occur.

You can create rules on the default event bus to identify specific events for EventBridge to send to one or more specified targets.

The following detail-types are available:

For tenant sending status changes:

For reputation findings:

Example EventBridge rule pattern for reputation findings:

{
  "detail-type": "Advisor Recommendation Status Open",
  "source": "aws.ses",
  "account": "012345678901",
  "time": "2023-11-15T17:00:59Z",
  "region": "us-east-1",
  "resources": [
    "arn:aws:ses:us-east-1:012345678901:tenant/{tenant-name}/{tenant-id}"
  ],
  "detail": { 
       "version": "1.0.0",
       "data": "The bounce rate exceeded 15.0% based on a representative volume of 197 emails from July 11, 2025 at 14:43 (UTC) to July 11, 2025 at 16:13 (UTC).",
       "metadata":{"impact":"HIGH","type":"BOUNCE"}
  
    }
}

Example EventBridge rule pattern for sending status changes:

{
        "detail-type": "Sending Status Disabled",
        "source": "aws.ses",
        "account": "012345678901",
        "time": "2025-07-24T12:44:28Z",
        "region": "us-east-1",
        "resources": [
            "arn:aws:ses:us-east-1:012345678901:tenant/{tenant-name}/{tenant-id}"
        ],
        "detail": {
            "version": "1.0.0",
            "data": {
                "origin": "CUSTOMER_MANAGED",
                "record": {
                    "status": "DISABLED",
                    "cause": "Status manually updated.",
                    "lastUpdatedTimestamp": [2025, 7, 24, 12, 44, 28, 995000000]
                }
            }
        }
    }

Field descriptions:

You can use these events to monitor tenant status changes and automate responses in your applications. For example, you might want to trigger alerts when tenants are disabled or track tenant health metrics over time.

Integration with AWS Trust & Safety

When AWS Trust & Safety detects issues that would normally result in account-level enforcement, the tenant system enables more targeted responses. Instead of pausing your entire account, Trust & Safety can pause only the problematic tenants while allowing compliant tenants to continue sending.

This tenant-level enforcement reduces the impact of reputation issues and helps maintain business continuity for your other email streams.

You'll receive notifications when SES has disabled sending due to high-severity issues affecting tenant reputation and has placed your account under review. A case will be opened for you in the AWS Support Center so that you can work with Trust & Safety to resolve issues and restore sending for the affected tenant.

Best practices

Follow these best practices to effectively manage tenant reputation in Amazon SES:

Limitations

When using tenant management, be aware of these limitations:

Pricing

There's an additional charge per tenant per month based on the number of emails. For detailed pricing information, see the SES pricing page.

When using CloudWatch with tenant metrics, the standard CloudWatch metrics for each tenant are provided at no additional cost as part of the basic monitoring. Additional CloudWatch features like custom dashboards, alarms, or detailed monitoring may incur standard CloudWatch charges.