Type annotations for boto3 SES

1.42.3 · active · verified Sun Apr 12

types-boto3-ses provides comprehensive type annotations for the Amazon Simple Email Service (SES) client within the `boto3` library. This package is part of the `mypy-boto3-builder` project, designed to enhance type checking, autocompletion, and static analysis for `boto3` users with tools like MyPy, Pyright, VSCode, and PyCharm. The current version is 1.42.3, with new releases typically following `boto3` updates and `mypy-boto3-builder` improvements.

Warnings

breaking As of mypy-boto3-builder version 8.12.0 (which generated types-boto3-ses 1.42.3), support for Python 3.8 has been explicitly removed. All `types-boto3` packages now require Python 3.9 or newer.
Fix: Upgrade your Python environment to 3.9 or higher.
breaking In `mypy-boto3-builder` version 8.9.0, there were breaking changes to TypeDef naming conventions. Specifically, some TypeDef names were shortened (e.g., `CreateDistributionRequestRequestTypeDef` became `CreateDistributionRequestTypeDef`) and conflicting `Extra` postfixes were moved (`CreateDistributionExtraRequestTypeDef` to `CreateDistributionRequestExtraTypeDef`). While not specific to SES, this change affects all generated service TypeDefs.
Fix: Review your codebase for direct imports and usage of TypeDef names and update them according to the new conventions.
gotcha Users of PyCharm may experience slow performance or high CPU usage when using `types-boto3` packages due to issues with PyCharm's type checker and `Literal` overloads. It is recommended to use `types-boto3-lite` for better performance or to configure PyCharm to use external type checkers like MyPy or Pyright.
Fix: Consider installing `types-boto3-lite-ses` instead (e.g., `pip install types-boto3-lite-ses`) or disable PyCharm's internal type checker and use MyPy/Pyright.
deprecated While not directly affecting SES, the `sms-voice` service was removed from generation in `mypy-boto3-builder` version 8.11.0, recommending the use of `pinpoint-sms-voice` instead. This highlights a pattern of service renames or deprecations that can occur within the AWS ecosystem and the `types-boto3` project.
Fix: Always refer to the latest AWS documentation for service names and use the corresponding `types-boto3` package or builder options.

Install

pip install types-boto3-ses Standalone installation
pip install 'types-boto3[ses]' As an extra with types-boto3

Imports

SESClient
```
from types_boto3_ses.client import SESClient
```
For explicit type hinting of the SES client object.
EmailAddressIdentity
```
from types_boto3_ses.type_defs import EmailAddressIdentity
```
For explicit type hinting of specific SES TypeDefs.
TYPE_CHECKING
```
from typing import TYPE_CHECKING
if TYPE_CHECKING:
    from types_boto3_ses.client import SESClient
```
Recommended for conditional import of type-only dependencies to avoid runtime overhead.

Quickstart

This example demonstrates how to initialize an SES client and use type annotations for both the client itself and its method responses. Type checkers will use `types-boto3-ses` to provide accurate suggestions and catch potential errors.

import os
from typing import TYPE_CHECKING

import boto3

# Conditionally import type hints only during type checking
if TYPE_CHECKING:
    from types_boto3_ses.client import SESClient
    from types_boto3_ses.type_defs import IdentityListResponseTypeDef

# Ensure AWS credentials are available for boto3
# For example, by setting AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY environment variables
# or configuring the AWS CLI.

def list_ses_identities() -> None:
    # boto3.client returns a dynamically typed client. With types-boto3-ses installed,
    # static analysis tools like mypy will correctly infer types.
    # For explicit type hints, you can annotate the client:
    client: SESClient = boto3.client("ses", region_name=os.environ.get('AWS_REGION', 'us-east-1'))

    try:
        # The response type will be correctly inferred by type checkers
        response: IdentityListResponseTypeDef = client.list_identities(IdentityType='EmailAddress')
        print("Verified SES Identities:")
        for identity in response.get('Identities', []):
            print(f"- {identity}")
    except client.exceptions.ClientError as e:
        print(f"Error listing SES identities: {e}")

if __name__ == "__main__":
    # Set a dummy region if not running in an AWS environment
    if 'AWS_REGION' not in os.environ:
        os.environ['AWS_REGION'] = 'us-east-1'
    list_ses_identities()

view raw JSON →