Skip to main content

AWS SES Mocking

This guide covers how to use proxymock to mock AWS Simple Email Service (SES) connections and API calls for local development and testing.

Introduction to AWS SES​

Amazon Simple Email Service (SES) is a cloud-based email sending service designed to help digital marketers and application developers send marketing, notification, and transactional emails. proxymock is able to record and mock AWS SES API calls. This allows you to test email functionality without actually sending emails, incurring AWS costs or triggering spam filters. To do this, we record your app talking to AWS SES and simulate the service in subsequent tests. To learn more about proxymock recording and architecture, work through the agent tutorial.

Demo App​

The following instructions will work with most AWS SDK clients. However, for demonstration purposes we'll use a simple application that sends emails via AWS SES. If you are using your own app skip ahead to recording for the environment variables you'll need.

This demo app is available in the speedscale/demo repository. If you'd like to use the demo app, clone the repository and navigate to the appropriate directory, which contains a basic email service that interacts with AWS SES:

git clone https://github.com/speedscale/demo && cd demo/go-ses-demo

Don't worry if you can't use this demo app. Just apply the environment variables to your own AWS SES client app.

Recording AWS SES Traffic​

The proxymock record command creates RRPair files from real AWS SES interactions. Each request will contain an SES API call (like SendEmail or SendRawEmail) and the response will contain the message ID and other metadata returned by AWS.

Start the Recorder​

Start a dedicated terminal window to run the proxymock recorder:

proxymock record

This tells the recorder to listen on port 4140 (the default) for HTTPS traffic and capture AWS SES API calls. You can learn more about how proxymock records on the architecture page.

AWS SES Client Configuration​

For proxymock to capture AWS SES traffic, configure your application to route API calls through the proxy using environment variables. Start a new terminal window that will run your application:

cd demo/go-ses-demo &&
FROM_EMAIL=matt@speedscale.com \
TO_EMAIL=matt@speedscale.com \
HTTP_PROXY=http://localhost:4140 \
HTTPS_PROXY=http://localhost:4140 \
go run main.go

The key ingredient is setting HTTP_PROXY and HTTPS_PROXY to redirect traffic to the proxymock recorder. Your AWS credentials should be configured normally (via environment variables, AWS config files, or IAM roles).

What Gets Recorded​

You can browse the recording in your browser with proxymock web:

proxymock web

proxymock captures AWS SES traffic as RRPair files containing:

  • Request Data: API operation (SendEmail, SendRawEmail, etc.), email content, recipients, subject lines
  • Response Data: Message IDs, success/error responses, metadata
  • Timing Information: API call latency and response times

The actual wire protocol is HTTPS/JSON but proxymock displays request and response data in a readable format. The underlying files can be modified if you want your mock to return different values or simulate failures. You can learn more about the structure of the underlying recording by looking at the proxymock directory containing the recording files and the docs.

Troubleshooting Recording​

  • Ensure your AWS SDK is configured to use the HTTP/HTTPS proxy
  • Check that proxy environment variables are set correctly
  • Verify your AWS credentials are valid and have SES permissions
  • Some SDKs may require additional proxy configuration

Starting the Mock Server​

Once you have recorded AWS SES traffic, you can replay it without actually sending emails or connecting to AWS.

Start the proxymock mock server:

proxymock mock

You can now run your application with the same proxy settings and it will receive mocked responses:

HTTP_PROXY=http://localhost:4140 \
HTTPS_PROXY=http://localhost:4140 \
go run main.go

Your application will behave as if it's sending emails through AWS SES, but no actual emails will be sent.

Modifying Responses​

To change a response by hand, edit its RRPair file. To change values on every run, save the transforms in a blueprint instead. Active blueprints in the workspace apply during proxymock mock and proxymock replay without rewriting the recording. They use the same transform engine as Speedscale Cloud, so you do not need to upload the snapshot.

Create and Verify Blueprints shows how to save transforms from proxymock web, preview their changes, and confirm they ran. Use a responder response chain to change the mock response returned to your app, or a responder request chain to change the request used for mock matching.

If your team already keeps a Traffic Transform Template in Speedscale Cloud, pull it into the workspace:

proxymock cloud pull transform <id>

The template is written to proxymock/blueprints/<id>.json, and the next proxymock mock applies it.

Common Use Cases​

Testing Error Scenarios​

Modify recorded responses to simulate SES errors:

  • Rate limiting errors (throttling)
  • Invalid email addresses
  • Bounce and complaint notifications
  • Service unavailability

Testing Email Content​

Verify your application correctly:

  • Formats email bodies (HTML and text)
  • Sets proper headers and metadata
  • Handles attachments in raw emails
  • Manages recipient lists

Integration Testing​

Use mocked SES in your CI/CD pipeline to:

  • Test email workflows without sending real emails
  • Avoid AWS costs during testing
  • Ensure consistent test results
  • Speed up test execution