# AWS setup
Source: https://docs.getsendbase.com/aws-setup

Learn how to create an IAM role and configure SES

This guide shows you how to create an IAM role and configure SES.

<Info>
  **Prerequisites**: You need an AWS account to complete this setup. If you
  don't have one, create it by following the
  [documentation](/best-practice/aws/create-aws-account).
</Info>

## Create an IAM Role

Use our CloudFormation template to automatically create an IAM role with all required permissions.

1. Click this link to launch the CloudFormation stack: [Create IAM Role Stack](https://console.aws.amazon.com/cloudformation/home#/stacks/create/review?stackName=sendbase-iam-role\&templateURL=https://sendbase.s3.amazonaws.com/aws/main.yaml).
2. Click **Create stack**.
3. Wait for the stack creation to complete. (status will show `CREATE_COMPLETE`)
4. Go to the **Outputs** tab to find your IAM Role ARN.

<Note>
  **IAM role is the safest way to grant access**. The CloudFormation template
  creates a role that grants minimal permissions corresponding to the
  application's use, only works with Sendbase, and cannot be used elsewhere.
</Note>

```json IAM Policy expandable theme={null}
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "SESGeneralAccess",
      "Effect": "Allow",
      "Action": [
        "ses:GetImportJob",
        "ses:CreateImportJob",
        "ses:GetAccount",
        "ses:TagResource",
        "ses:CreateEmailIdentity",
        "ses:GetEmailIdentity",
        "ses:PutEmailIdentityMailFromAttributes",
        "ses:DeleteEmailIdentity",
        "ses:SendEmail",
        "ses:SendTemplatedEmail",
        "ses:SendBulkEmail",
        "ses:SendBulkTemplatedEmail"
      ],
      "Resource": "*"
    },
    {
      "Sid": "SESContactListAccess",
      "Effect": "Allow",
      "Action": [
        "ses:GetContactList",
        "ses:CreateContactList",
        "ses:UpdateContactList",
        "ses:DeleteContactList",
        "ses:ListContacts",
        "ses:GetContact",
        "ses:CreateContact",
        "ses:UpdateContact",
        "ses:DeleteContact"
      ],
      "Resource": "arn:aws:ses:*:*:contact-list/sendbase*"
    },
    {
      "Sid": "SESConfigurationSetAccess",
      "Effect": "Allow",
      "Action": [
        "ses:GetConfigurationSet",
        "ses:CreateConfigurationSet",
        "ses:DeleteConfigurationSet",
        "ses:GetConfigurationSetEventDestinations",
        "ses:CreateConfigurationSetEventDestination",
        "ses:UpdateConfigurationSetEventDestination",
        "ses:DeleteConfigurationSetEventDestination"
      ],
      "Resource": "arn:aws:ses:*:*:configuration-set/sendbase*"
    },
    {
      "Sid": "SESEmailTemplateAccess",
      "Effect": "Allow",
      "Action": [
        "ses:GetEmailTemplate",
        "ses:CreateEmailTemplate",
        "ses:UpdateEmailTemplate",
        "ses:DeleteEmailTemplate"
      ],
      "Resource": "arn:aws:ses:*:*:template/sendbase*"
    },
    {
      "Sid": "S3Access",
      "Effect": "Allow",
      "Action": [
        "s3:ListBucket",
        "s3:CreateBucket",
        "s3:DeleteBucket",
        "s3:PutBucketPolicy",
        "s3:GetBucketPublicAccessBlock",
        "s3:PutBucketPublicAccessBlock",
        "s3:GetObject",
        "s3:PutObject",
        "s3:DeleteObject",
        "s3:PutObjectAcl",
        "s3:PutBucketTagging"
      ],
      "Resource": ["arn:aws:s3:::sendbase*", "arn:aws:s3:::sendbase*/*"]
    },
    {
      "Sid": "CloudWatchMetricsAccess",
      "Effect": "Allow",
      "Action": ["cloudwatch:GetMetricData"],
      "Resource": "*"
    },
    {
      "Sid": "SNSTopicAccess",
      "Effect": "Allow",
      "Action": [
        "sns:GetTopicAttributes",
        "sns:CreateTopic",
        "sns:DeleteTopic",
        "sns:TagResource"
      ],
      "Resource": "arn:aws:sns:*:*:sendbase*"
    },
    {
      "Sid": "SNSSubscriptionAccess",
      "Effect": "Allow",
      "Action": [
        "sns:ListSubscriptionsByTopic",
        "sns:Subscribe",
        "sns:Unsubscribe"
      ],
      "Resource": "arn:aws:sns:*:*:sendbase*"
    }
  ]
}
```

## Move SES out of Sandbox

SES starts in sandbox mode, limiting email sending to verified addresses only. To send emails to any address, you need production access.

### Request Production Access

1. Open the [Amazon SES console](https://console.aws.amazon.com/ses/).
2. Ensure you're in your preferred region.
3. In the navigation panel, choose **Account dashboard**.
4. In the warning box at the top of the console, choose **View Get set up page**, then **Request production access**.
5. Fill out the production access request and choose **Submit request**.

<Info>
  Once you submit your account details for review, you cannot edit them until
  the review is complete. The AWS Support team provides an initial response to
  your request within 24 hours.
</Info>

### Generate Your Use Case Description

To help you craft an use case description, we've created a prompt that transforms your basic business information into a professional AWS SES production access request.

**Prerequisites:**

* **Sending pattern**: Use the sandbox environment for a while to establish a good sending pattern
* **Email authentication**: Set up email authentication (DKIM, SPF, and DMARC records) for your domain
* **Professional website**: Set up a professional website on your domain with a privacy policy

**Generate a professional production access request with your preferred AI assistant:**

1. Copy the prompt below and paste it into your preferred AI assistant (ChatGPT, Claude, etc.).
2. Fill out the **Business Info** and **Email Program** sections with your information.
   The **Technical Setup** section is pre-filled according to what the system does.
3. Generate the detailed production access request and submit it.

```md expandable theme={null}
# SES Use Case Description Generator

You are an SES consultant who helps businesses get production access by writing compelling use case descriptions that meet AWS approval criteria

## Instructions

Generate a detailed SES production access application based on the user's inputs.
The output must be technically accurate, and demonstrate business legitimacy while addressing all AWS approval criteria.

## Required Input Format

Ask the user to provide the following information in a simple form:

Business Info:

- Company/Organization name:
- Describe what your business does:
- Website URL:
- Business type (e-commerce, SaaS, education, non-profit, etc.):

Email Program:

- Email list size (approximate):
- How you collect email addresses (website signup, events, etc.):
- Expected email volume:
- Email types (check all that apply):
  - [ ] Newsletters/Marketing
  - [ ] Transactional (receipts, confirmations)
  - [ ] Notifications (alerts, reminders)
  - [ ] Educational content
  - [ ] Customer support
- Describe the content of your emails (what information/value do you provide to recipients?):

Technical Setup:

- Do you have bounce/complaint handling?
  A. We have implemented automated bounce and complaint handling using AWS SES feedback notifications via SNS topics.
  Our system processes hard bounces and complaints in real-time, automatically updating the contact list to suppress future sends to those addresses.
- How do you handle unsubscribes?
  A. Every email we send includes a clear, prominent unsubscribe link in the footer.
  We also implement List-Unsubscribe and List-Unsubscribe-Post headers to support one-click unsubscribe functionality.
  Unsubscribe requests are processed immediately and automatically.
- How do you handle monitoring and reputation management?
  A. We continuously monitor bounce rates and complaint rates at both the account level and per-campaign level in real-time.
  We track delivery rates and engagement metrics.
  We regularly review our sending patterns to identify and address any issues promptly.

## Output Structure

Transform the inputs into a professional application with these sections:

### 1. Business Overview

- Brief description of company and services
- State specific email communication needs

### 2. Email Program Details

- Detail email list composition
- Explain opt-in collection methods with emphasis on consent (ask if this is not provided or detailed)
- Break down email types and describe the specific content/value provided to recipients
- Justify sending volumes based on business needs

### 3. Technical Setup

- Detail bounce and complaint handling systems (ask to set this up if it's not prepared)
- Explain unsubscribe mechanisms (ask to set this up if it's not prepared)
- Include monitoring and reputation management procedures (ask to set this up if it's not prepared)

## Tone and Style Guidelines

- Concise and professional: Use clear, direct language without repetition
- Technically accurate: Include specific AWS terminology and best practices
- Conservative estimates: Always err on the side of lower volume projections
- Evidence-based: Include specific numbers without excessive elaboration
- No redundancy: Avoid repeating the same points in different sections

## Key Success Factors to Include

Always incorporate these elements regardless of user input:

1. Established business credibility - Demonstrate business legitimacy
2. Opt-in collection methods - Emphasize consent and legal compliance
3. Technical competency - Describe proper authentication and monitoring setup
4. Automated bounce/complaint handling - Detail specific technical implementation
5. Multiple unsubscribe options - Show user-friendly opt-out processes
6. Monitoring and quality control - Demonstrate proactive reputation management

## Important Notes

- Keep output under 4,000 characters
- Be concise: Avoid repetitive explanations and unnecessary detail

## Sample Interaction

**User Input:**

- Company: "FitLife Supplements"
- Website: "fitlifesupplements.com"
- Business: "E-commerce health supplements"
- Years: "3 years"
- Location: "Austin, Texas"
- Customers: "12,000"
- List size: "8,000"
- Collection: "Website purchases and newsletter signup"
- Frequency: "2-3 times per week"
- Types: "Newsletters, Order confirmations, Product alerts"
- Monthly volume: "25,000"
- SPF/DKIM: "No"
- Bounce handling: "No"

**Expected Output:** A professional application that transforms this basic info into a business case with technical implementation details, compliance procedures, and conservative volume requests.
```

<Note>
  You must review and revise the generated request thoroughly before submitting
  it.
</Note>


# Create AWS Account
Source: https://docs.getsendbase.com/best-practice/aws/create-aws-account

Learn how to create an AWS account

## Create an AWS account

Follow these steps to create and activate your new AWS account.

### Initial setup

1. Visit the [AWS home page](https://aws.amazon.com/).

2. Choose **Create account**.

3. Enter your root user email address.

4. Create and confirm your password.

### Account information

1. Select **Personal or Business** for your account.

2. Enter your contact information.

3. Accept the [AWS Customer Agreement](https://aws.amazon.com/agreement/).

<Note>
  If you select Business, you should avoid individual email address. For
  example, `it.admins@example.com` is better than `paulo.santos@example.com`.
</Note>

### Payment setup

1. Add a [valid payment method](https://console.aws.amazon.com/billing/home#/paymentmethods).

2. Verify your billing address.

### Identity verification

1. Enter your phone number.

2. Receive and enter the verification code.

3. If there's a CAPTCHA, then enter the displayed code and choose **Submit**.

4. If you're an India-based account, [then complete additional verification if required](https://docs.aws.amazon.com/awsaccountbilling/latest/aboutv2/manage-account-payment-aispl.html).

### Choose a support plan

1. Select from [available AWS Support plans](https://aws.amazon.com/premiumsupport/features).

2. Choose **Complete sign up**.

<Info>
  Account activation typically takes minutes, but it can take up to 24 hours.
  When account activation is complete, you receive a confirmation email.
</Info>

## Best practice

### Enable MFA for root user

After creating your AWS account, enable multi-factor authentication (MFA) for your root user to add an extra layer of security.

<img alt="Navigation bar" />

1. Sign in to the [AWS Management Console](https://console.aws.amazon.com/) using your root user credentials.

2. On the right side of the navigation bar, choose your account name and select **Security credentials**.

3. In the **Multi-Factor Authentication (MFA)** section, choose **Assign MFA device**.

4. Type a **Device name**, choose **Authenticator app**, and select **Next**.

5. Configure your authenticator app:
   * Open your virtual MFA app (such as Google Authenticator, Microsoft Authenticator, or Authy)
   * Select **Show QR code** and scan it with your app, or select **Show secret key** to manually enter it

6. Complete the registration:
   * Enter the six-digit code from your app in the **MFA code 1** box
   * Wait up to 30 seconds for a new code to generate
   * Enter the new code in the **MFA code 2** box
   * Choose **Add MFA**

<Warning>
  Securely backup the QR code or secret key. If you lose access to your MFA
  device and have no backup MFA devices, you may be locked out of your account
  and need to contact AWS Support.
</Warning>

## Additional resources

* [How do I create and activate a new AWS account?](https://youtu.be/lIdh92JmWtg?si=SEzOchi-1lmPvshY)


# Request Production Access
Source: https://docs.getsendbase.com/best-practice/aws/production-access

Learn how to request production access

## What is the sandbox mode?

To prevent fraud and abuse, and to protect your reputation, AWS places all new SES accounts in the sandbox mode. In the sandbox mode, your SES account has restrictions: you can only send email to verified email addresses or domains, and you have limited sending quotas.

## Request Production Access

To move out of sandbox mode, you need to [request production access](https://docs.aws.amazon.com/ses/latest/dg/request-production-access.html) through the AWS console. AWS is very strict about approving production access requests and does not provide feedback when requests are rejected. This makes it critical to submit a complete and well-prepared request. \*\*Here is how you can increase the probability of approval\*\*.

### Build Trust

Building trust is the key to getting approval. AWS wants to see that you're running a legitimate business, not a potential spammer. These steps demonstrate your business legitimacy:

* **Sending pattern**: Use the sandbox environment for a while to establish a good sending pattern
* **Email authentication**: Set up email authentication (DKIM, SPF, and DMARC records) for your domain
* **Professional website**: Set up a professional website on your domain with a privacy policy

### Request with Enhanced Details

When you request production access through the AWS console, you'll need to provide detailed information about your business, email program, and technical setup.
The more specific your answers, the higher your chances of approval.
Below are the key questions you should prepare for.

<Info>
  To help you craft an use case description, we've created a
  [prompt](/best-practice/aws/production-access#generate-your-use-case-description).
  This prompt generates an use case description containing answers to the
  following questions.
</Info>

#### Business Information

* **Company/Organization Name**: Provide your official business name
* **Business Description**: Explain what your business does and why you need to send emails
* **Website URL**: Include your live website that has a privacy policy

#### Email Program

* **Email List Size**: Provide an approximate number of recipients. Be realistic and start with a reasonable volume
* **List Collection Method**: Explain how you obtain email addresses (e.g., sign-ups on your website, customer accounts, opt-in forms). Emphasize that you never purchase or rent email lists
* **Email Types**: Specify whether you'll send transactional emails (order confirmations, password resets), marketing emails (newsletters, promotions), or both. Describe the content and purpose of each type

#### Technical Setup

* **Bounce and Complaint Handling**: Describe your process for handling hard bounces and unsubscribing users who mark emails as spam. Mention if you're using SES feedback notifications (SNS topics or configuration sets) to track and process these events.
* **Unsubscribe Process**: Explain how recipients can easily unsubscribe from your emails (e.g., unsubscribe link in every email, one-click unsubscribe headers). Include that you'll honor unsubscribe requests promptly
* **Monitoring and Reputation**: Detail how you'll track your sending metrics (bounce rates, complaint rates, delivery rates) and maintain a good sender reputation. Mention any tools or dashboards you'll use to monitor email performance and take corrective action when needed

### Generate Your Use Case Description

1. Copy the prompt below and paste it into your preferred AI assistant (ChatGPT, Claude, etc.).
2. Fill out the **Business Info** and **Email Program** sections with your information.
   The **Technical Setup** section is pre-filled according to what the system does.
3. Generate the detailed production access request and submit it.

```md expandable theme={null}
# SES Use Case Description Generator

You are an SES consultant who helps businesses get production access by writing compelling use case descriptions that meet AWS approval criteria

## Instructions

Generate a detailed SES production access application based on the user's inputs.
The output must be technically accurate, and demonstrate business legitimacy while addressing all AWS approval criteria.

## Required Input Format

Ask the user to provide the following information in a simple form:

Business Info:

- Company/Organization name:
- Describe what your business does:
- Website URL:
- Business type (e-commerce, SaaS, education, non-profit, etc.):

Email Program:

- Email list size (approximate):
- How you collect email addresses (website signup, events, etc.):
- Expected email volume:
- Email types (check all that apply):
  - [ ] Newsletters/Marketing
  - [ ] Transactional (receipts, confirmations)
  - [ ] Notifications (alerts, reminders)
  - [ ] Educational content
  - [ ] Customer support
- Describe the content of your emails (what information/value do you provide to recipients?):

Technical Setup:

- Do you have bounce/complaint handling?
  A. We have implemented automated bounce and complaint handling using AWS SES feedback notifications via SNS topics.
  Our system processes hard bounces and complaints in real-time, automatically updating the contact list to suppress future sends to those addresses.
- How do you handle unsubscribes?
  A. Every email we send includes a clear, prominent unsubscribe link in the footer.
  We also implement List-Unsubscribe and List-Unsubscribe-Post headers to support one-click unsubscribe functionality.
  Unsubscribe requests are processed immediately and automatically.
- How do you handle monitoring and reputation management?
  A. We continuously monitor bounce rates and complaint rates at both the account level and per-campaign level in real-time.
  We track delivery rates and engagement metrics.
  We regularly review our sending patterns to identify and address any issues promptly.

## Output Structure

Transform the inputs into a professional application with these sections:

### 1. Business Overview

- Brief description of company and services
- State specific email communication needs

### 2. Email Program Details

- Detail email list composition
- Explain opt-in collection methods with emphasis on consent (ask if this is not provided or detailed)
- Break down email types and describe the specific content/value provided to recipients
- Justify sending volumes based on business needs

### 3. Technical Setup

- Detail bounce and complaint handling systems (ask to set this up if it's not prepared)
- Explain unsubscribe mechanisms (ask to set this up if it's not prepared)
- Include monitoring and reputation management procedures (ask to set this up if it's not prepared)

## Tone and Style Guidelines

- Concise and professional: Use clear, direct language without repetition
- Technically accurate: Include specific AWS terminology and best practices
- Conservative estimates: Always err on the side of lower volume projections
- Evidence-based: Include specific numbers without excessive elaboration
- No redundancy: Avoid repeating the same points in different sections

## Key Success Factors to Include

Always incorporate these elements regardless of user input:

1. Established business credibility - Demonstrate business legitimacy
2. Opt-in collection methods - Emphasize consent and legal compliance
3. Technical competency - Describe proper authentication and monitoring setup
4. Automated bounce/complaint handling - Detail specific technical implementation
5. Multiple unsubscribe options - Show user-friendly opt-out processes
6. Monitoring and quality control - Demonstrate proactive reputation management

## Important Notes

- Keep output under 4,000 characters
- Be concise: Avoid repetitive explanations and unnecessary detail

## Sample Interaction

**User Input:**

- Company: "FitLife Supplements"
- Website: "fitlifesupplements.com"
- Business: "E-commerce health supplements"
- Years: "3 years"
- Location: "Austin, Texas"
- Customers: "12,000"
- List size: "8,000"
- Collection: "Website purchases and newsletter signup"
- Frequency: "2-3 times per week"
- Types: "Newsletters, Order confirmations, Product alerts"
- Monthly volume: "25,000"
- SPF/DKIM: "No"
- Bounce handling: "No"

**Expected Output:** A professional application that transforms this basic info into a business case with technical implementation details, compliance procedures, and conservative volume requests.
```

<Note>
  You must review and revise the generated request thoroughly before submitting
  it.
</Note>


# Introduction
Source: https://docs.getsendbase.com/introduction

Send marketing emails with AWS SES, not just transactional.

<Columns>
  <Card title="Quickstart" icon="book-open" href="/quickstart">
    Send your first email with our step-by-step guide
  </Card>

  <Card title="AWS setup" icon="aws" href="/aws-setup">
    Create IAM role and configure AWS SES to start sending emails
  </Card>

  <Card title="How it works" icon="lightbulb" href="/learn/how-it-works">
    Understand how Sendbase leverages your AWS account
  </Card>

  <Card title="Sending emails" icon="send" href="/learn/broadcasts">
    Learn how to send email campaigns to your contacts
  </Card>
</Columns>


# Broadcasts
Source: https://docs.getsendbase.com/learn/broadcasts

Learn how to send emails to your contacts

Broadcasts let you send emails to your subscribed contacts at once.

<video />

1. Click the **Create Broadcast** button from the navigation panel
2. Choose a verified sender from the **From** field dropdown
3. Write your email subject line and compose your content in the editor
4. Click **Send Email** and configure your quota usage settings (see [Quota Configuration](#quota-configuration) below)
5. Click **Send** to start sending to all subscribed contacts
6. Monitor your email performance with metrics including delivery rate, bounce rate, open rate, and click rate

## Quota Configuration

Since broadcasts can consume large amounts of your quota, it's important to control how much capacity they use. This prevents a single broadcast from using your entire quota.

AWS SES enforces two types of limits on your account:

* **Daily quota**: Maximum number of emails you can send in a 24-hour period
* **Send rate**: Maximum number of emails you can send per second

When you configure a broadcast's quota usage percentage, the system proportionally allocates both limits. For example, if you set 50% quota usage and your account has a 50,000 daily quota with 14 emails/second send rate, the broadcast will use 25,000 emails/day and 7 emails/second.

## Unsubscribe Handling

The system provides multiple layers of unsubscribe functionality to ensure compliance and maintain a healthy sender reputation:

### Automatic Unsubscription

Contacts are automatically unsubscribed when AWS SES reports a bounce or complaint event. This helps protect your sender reputation and ensures you don't continue sending to invalid or unwilling recipients.

### Manual Unsubscribe Options

We provides two ways that allow users to unsubscribe manually.

<video />

1. **Unsubscribe footer (your responsibility)**: You should manually include an unsubscribe link in your email content.
   The editor provides an unsubscribe block that you can insert.
   The unsubscribe link must be `https://getsendbase.com/unsubscribe?token={{unsubscribeToken}}` to properly identify and unsubscribe recipients

2. **Unsubscribe headers (automatic)**: The system automatically adds unsubscribe headers to every email. These headers allow email clients to display built-in unsubscribe options, providing an additional compliance layer.

## Broadcast Statuses

Here are all the statuses that a broadcast can have:

* `draft`: The broadcast is being composed
* `queued`: The broadcast is waiting to be processed for sending
* `in_progress`: The broadcast is currently being sent to contacts
* `published`: The broadcast has been successfully sent to all contacts
* `paused`: The system paused the publishing process

## Limitations

### Template Variables

Broadcasts currently do not support template variables for personalization beyond the built-in `{{unsubscribeUrl}}` and `{{unsubscribeToken}}` variables.

This limitation exists because the **GetContact** API retrieving contact has a rate limit of 1 request per second, making it impractical to fetch personalization data when sending to thousands of contacts.


# Contacts
Source: https://docs.getsendbase.com/learn/contacts

Learn how to manage your email contacts

## Managing Contacts

Contacts are the email addresses you send emails to. It provides three ways to manage your contacts.

### 1. Console Management

Add, view, and manage contacts directly through the web interface:

<video />

### 2. Bulk File Upload

Import or delete contacts in bulk by uploading a CSV or JSON file:

1. Click **Import Contacts** in the contacts page
2. Select your file (CSV or JSON format)
3. Choose action: **Add contacts** or **Delete contacts**

```csv CSV format theme={null}
emailAddress,unsubscribeAll,attributesData
john.doe@example.com,false,"{""Name"": ""John"", ""Company"": ""ACM Inc""}"
jane.smith@example.com,true,"{""Name"": ""Jane"", ""Company"": null}"
```

```json JSON format expandable theme={null}
{
     "emailAddress": "john.deo@example.com",
     "unsubscribeAll": false,
     "attributesData": "{\"Name\":\"John\"}"
}
{
     "emailAddress": "jane.smith@example.com",
     "unsubscribeAll": true,
}
```

### 3. AWS SES API

Access contacts programmatically using AWS SES APIs. You can use your prefered language to manage your contacts.

Click **AWS API** in the contacts page to get your specific region and contact list name.

#### List Contacts

<CodeGroup>
  ```bash AWS CLI theme={null}
  aws sesv2 list-contacts \
    --region "<your-region>" \
    --contact-list-name "<your-contact-list-name>"
  ```

  ```javascript JavaScript SDK theme={null}
  import * as AWS from "@aws-sdk/client-sesv2";

  const client = new AWS.SESv2({
    region: "<your-region>",
  });

  const { Contacts } = await client.listContacts({
    ContactListName: "<your-contact-list-name>",
    PageSize: 100,
  });
  ```
</CodeGroup>

#### Get Contact

<CodeGroup>
  ```bash AWS CLI theme={null}
  aws sesv2 get-contact \
    --region "<your-region>" \
    --contact-list-name "<your-contact-list-name>" \
    --email-address "<email-address>"
  ```

  ```javascript JavaScript SDK theme={null}
  import * as AWS from "@aws-sdk/client-sesv2";

  const client = new AWS.SESv2({
    region: "<your-region>",
  });

  const contact = await client.getContact({
    ContactListName: "<your-contact-list-name>",
    EmailAddress: "<email-address>",
  });
  ```
</CodeGroup>

#### Add Contact

<CodeGroup>
  ```bash AWS CLI theme={null}
  aws sesv2 create-contact \
    --region "<your-region>" \
    --contact-list-name "<your-contact-list-name>" \
    --email-address "<email-address>" \
    --attributes-data '{"<key>": "<value>"}'
  ```

  ```javascript JavaScript SDK theme={null}
  import * as AWS from "@aws-sdk/client-sesv2";

  const client = new AWS.SESv2({
    region: "<your-region>",
  });

  await client.createContact({
    ContactListName: "<your-contact-list-name>",
    EmailAddress: "<email-address>",
    AttributesData: {
      "<key>": "<value>",
    },
  });
  ```
</CodeGroup>

#### Update Contact

<CodeGroup>
  ```bash AWS CLI theme={null}
  aws sesv2 update-contact \
    --region "<your-region>" \
    --contact-list-name "<your-contact-list-name>" \
    --email-address "<email-address>" \
    --attributes-data '{"<key>": "<value>"}'
  ```

  ```javascript JavaScript SDK theme={null}
  import * as AWS from "@aws-sdk/client-sesv2";

  const client = new AWS.SESv2({
    region: "<your-region>",
  });

  await client.updateContact({
    ContactListName: "<your-contact-list-name>",
    EmailAddress: "<email-address>",
    AttributesData: {
      "<key>": "<value>",
    },
  });
  ```
</CodeGroup>

#### Delete Contact

<CodeGroup>
  ```bash AWS CLI theme={null}
  aws sesv2 delete-contact \
    --region "<your-region>" \
    --contact-list-name "<your-contact-list-name>" \
    --email-address "<email-address>"
  ```

  ```javascript JavaScript SDK theme={null}
  import * as AWS from "@aws-sdk/client-sesv2";

  const client = new AWS.SESv2({
    region: "<your-region>",
  });

  await client.deleteContact({
    ContactListName: "<your-contact-list-name>",
    EmailAddress: "<email-address>",
  });
  ```
</CodeGroup>

## Attribute Data

Attribute data is custom key-value pairs that you can attach to each contact. This allows you to store additional information about your contacts, such as their name, company, or any other relevant data.

<Note>Attribute data must be a JSON object.</Note>

## Where Contacts Are Stored

**Contacts are stored in AWS SES Contact Lists, not in our database.** This means:

* Your contact data never leaves your AWS account
* You have full ownership and control of your contacts
* Direct access to your contacts through AWS SES APIs

## Additional resources

* [Using list management](https://docs.aws.amazon.com/ses/latest/dg/sending-email-list-management.html)
* [SES API](https://docs.aws.amazon.com/ses/latest/APIReference-V2/Welcome.html)


# Email Identities
Source: https://docs.getsendbase.com/learn/email-identities

Set up and verify your email sending domains

Email identities are domains you send emails from. You must verify domain ownership before sending emails through AWS SES.

1. Navigate to **Email Identities** > **Create identity**.
   Enter your domain (e.g., `example.com`), and click **Create**
2. Open the identity, copy DKIM CNAME records, add to your DNS provider (verification typically takes 5-10 minutes, up to 72 hours)
3. After verification, go to **Senders** tab > **Add sender**, enter email address using your domain (e.g., `hello@example.com`) and optional display name

<Warning>DKIM verification is **required** before sending emails.</Warning>

## DomainKeys Identified Mail (DKIM)

DKIM prevents email spoofing by adding digital signatures to email headers. AWS SES generates cryptographic keys: the public key is published in DNS, and emails are signed with the private key.

### Setup

AWS SES generates three DKIM CNAME tokens. Add all three records to your DNS provider:

| Field     | Value                            |
| --------- | -------------------------------- |
| **Type**  | CNAME                            |
| **Name**  | `{token}._domainkey.example.com` |
| **Value** | `{token}.dkim.amazonses.com`     |

## Mail FROM Domain

The Mail FROM domain appears in the email's envelope, separate from the "From" header recipients see.

### Setup

1. **Authentication** tab > **Mail FROM** > **Enable**
2. Enter subdomain (e.g., `mail`)
3. Choose MX failure behavior (recommend: **Use default value**)
4. Add DNS records:

| Field        | Value                                  |
| ------------ | -------------------------------------- |
| **Type**     | MX                                     |
| **Name**     | `mail.example.com`                     |
| **Priority** | 10                                     |
| **Value**    | `feedback-smtp.{region}.amazonses.com` |

| Field     | Value                               |
| --------- | ----------------------------------- |
| **Type**  | TXT                                 |
| **Name**  | `mail.example.com`                  |
| **Value** | `v=spf1 include:amazonses.com ~all` |

<Info>
  Mail FROM is **highly recommended** but optional for production sending.
</Info>

## DMARC

DMARC builds on SPF and DKIM, telling email servers how to handle failed authentication.

### Setup

Add TXT record to your DNS provider:

| Field     | Value                |
| --------- | -------------------- |
| **Type**  | TXT                  |
| **Name**  | `_dmarc.example.com` |
| **Value** | `v=DMARC1; p=none;`  |

**Policy options (`p=`):**

* `none`: Monitor only (start here)
* `quarantine`: Send suspicious emails to spam
* `reject`: Block failed emails

<Warning>
  Start with `p=none`, then gradually move to `p=quarantine` and `p=reject`
  after reviewing reports.
</Warning>


# Email Templates
Source: https://docs.getsendbase.com/learn/email-templates

Create reusable email templates

Email Templates allow you to create, save, and reuse email designs.

1. Click **Create template** from the email templates page
2. Use the block-based editor to compose your email content and design
3. Click the **Save** button to sync your changes to AWS SES

## Send Email with Template

After saving your template, you can send emails using the AWS SES API. The template is stored in AWS SES with the name format(i.e.,`sendbase-<template id>`).

<CodeGroup>
  ```bash AWS CLI theme={null}
  aws sesv2 send-email \
    --region "<your-region>" \
    --from-email-address "<from-email-address>" \
    --destination "ToAddresses=<recipient-email-address>" \
    --content 'Template={TemplateName=<template-name>,TemplateData={"<key>": "<value>"}}'
  ```

  ```javascript JavaScript SDK theme={null}
  import * as AWS from "@aws-sdk/client-sesv2";

  const client = new AWS.SESv2({
    region: "<your-region>",
  });

  await client.sendEmail({
    FromEmailAddress: "<from-email-address>",
    Destination: {
      ToAddresses: ["<recipient-email-address>"],
    },
    Content: {
      Template: {
        TemplateName: "<template-name>",
        TemplateData: JSON.stringify({ "<key>": "<value>" }),
      },
    },
  });
  ```
</CodeGroup>

<Info>
  If you'd like to manage the content by `git`, copy the HTML and plain text
  using the **Copy HTML** button from the test email actions menu.
</Info>

## Auto-Save

The editor automatically saves your changes to the database as you type (with 1 second debounce). These are stored as "dirty" values and don't sync to AWS SES until you explicitly click **Save**.

## Test Emails

Send test emails directly from the template editor to preview your design. Test emails use your current unsaved changes, allowing you to test before committing to AWS SES.

## Template Variable

Template variables allow you to write personalized emails for each recipient.

<video />

When the email is sent, template variables are replaced with the template data.

<Warning>If you personalize an email you have to pass template data. </Warning>


# How it works
Source: https://docs.getsendbase.com/learn/how-it-works

Understand how Sendbase uses your AWS account

Sendbase uses your AWS account to store and manage all email resources.

## Architecture

```mermaid theme={null}
graph TB
    User[User]

    subgraph Sendbase["Sendbase"]
        App[App]
        Queue[Queue]
    end

    subgraph AWS["User's AWS Account"]
        SES[SES]
        S3[S3]
        CloudWatch[CloudWatch]
        SNS[SNS]
    end

    User -->|Access AWS via| App
    App -->|Enqueue broadcast jobs| Queue
    Queue -->|Send emails| SES
    App -->|Store assets| S3
    App -->|Collect metrics| CloudWatch

    SES -->|Email delivery| Recipients[Recipients]
    SES -->|Event notifications| SNS
    SNS -->|Webhook events| App

    style AWS fill:#ff9900,stroke:#232f3e,stroke-width:3px,color:#fff
    style Sendbase fill:#4a9eff,stroke:#333,stroke-width:2px,color:#fff
```

* **Sending Email**: All email sending operations are executed directly through AWS SES.
* **Contact List**: Contacts are stored and retrieved directly through contact list API, not in our database.
* **Email Templates**: Email templates are stored in AWS SES.
* **Email Identity**: Verified domains are configured and stored in AWS SES.
* **S3**: Assets like images and contacts to import are stored in your S3 bucket.
* **SNS**: SES configuration sets publish email events (sends, deliveries, bounces, complaints, opens, clicks) to SNS topics, which then send webhooks to Sendbase for message logs.
* **Metrics**: Email analytics (delivery rates, bounces, complaints, opens, clicks) are collected from AWS CloudWatch.

## Benefits of This Architecture

* **Cost Efficiency**: Pay only AWS SES rates (100x cheaper than traditional email services).
* **Data Ownership**: All your data stays in your AWS account with no platform lock-in.
* **Dedicated Email Reputation**: Your sending reputation is isolated to your AWS account.
* **Scalability**: Leverage AWS's infrastructure and your SES sending limits.
* **Security**: Your data remain under your control.


# Message Logs
Source: https://docs.getsendbase.com/learn/message-logs

Track email delivery status, opens, clicks, and other events in real-time

Message Logs enables you to monitor and track all email events in real-time, including delivery status, bounces, complaints, opens, and clicks.

<video />

1. Click the **Enable Message Logs** button on the Message Logs page
2. Click **AWS API** button and copy the configuration set name from the code example
3. Include the configuration set name in your AWS SES API calls

```javascript Example theme={null}
await client.sendEmail({
  FromEmailAddress: "<from-email-address>",
  Destination: { ToAddresses: ["<recipient-email-address>"] },
  ConfigurationSetName: "<log-configuration-set-name>", // Copy this from AWS API button
  Content: {
    /* ... */
  },
});
```

<Note>
  Emails sent **without** the configuration set name will not be tracked.
</Note>

## Delivery Summary

The Message Logs page displays a summary of your email delivery and engagement metrics at a glance.

* **Delivered**: Percentage of emails successfully delivered to recipients' mail servers
* **Bounced**: Percentage of emails that bounced (hard or soft bounces)
* **Open Rate**: Percentage of delivered emails that were opened by recipients
* **Click Rate**: Percentage of delivered emails where recipients clicked on links

## Monitor Another Configuration Set

If you want to monitor another configuration set, you should **configure your configuration set destination** with an SNS topic created by Sendbase.
The SNS topic name starts with `sendbase-log-<id>`.

## Tracked Events

| Event Type             | Description                                                      |
| ---------------------- | ---------------------------------------------------------------- |
| **SEND**               | Email was successfully sent from SES                             |
| **DELIVERY**           | Email was successfully delivered to the recipient's mail server  |
| **BOUNCE**             | Email bounced (hard or soft bounce)                              |
| **COMPLAINT**          | Recipient marked the email as spam                               |
| **REJECT**             | SES rejected the email (invalid recipient, configuration issues) |
| **OPEN**               | Recipient opened the email                                       |
| **CLICK**              | Recipient clicked a link in the email                            |
| **RENDERING\_FAILURE** | Email template failed to render                                  |
| **DELIVERY\_DELAY**    | Temporary delivery delay occurred                                |

<Info>
  When a **Bounce** or **Complaint** event is received, the contact is
  automatically unsubscribed if they exist in the project's contact list.
</Info>

## Data Retention

Email logs are automatically deleted after **7 days** to manage storage costs and comply with data retention best practices. An automated cleanup job runs every hour to remove expired logs.

If you need longer retention:

* Set up your own custom CloudWatch or S3-based logging solution
* Contact support for retention options


# Quickstart
Source: https://docs.getsendbase.com/quickstart

Broadcast your first email

This quickstart guide shows you how to broadcast your first email.

<video />

## Set Up AWS

Sendbase will require an AWS IAM role after you sign up. You can create an IAM role following the [instruction](/aws-setup#create-an-iam-role).

1. Enter your **IAM role ARN** you created as prerequisites.
2. Select the **Region**.
3. Click **Initialize Project** to set up the project.

## Verify Domain

AWS SES provides a domain verification process to ensure that your domain is properly configured for email sending.

1. In the navigation panel, click on **Email Identities**.
2. Click **Add Identity** and enter your domain.
3. Go to the detail page and you can find DKIM settings.
4. Copy the domain verification CNAME record and add it to your DNS settings.
5. Wait for the verification to complete. (it takes an average of 5 to 10 minutes)

## Add Senders

After you have verified your domain, you can add a sender identity to send emails.

1. In the detail page of your email identity, click on **Add Sender**.
2. Enter the sender's email address and click **Add**.

## Add Contacts

1. In the navigation panel, click on **Contacts**.
2. Two options are available to add contacts:
   * **Individual contacts**: Click on **Create New Contact** and enter email addresses separated by commas.
   * **Bulk import**: Click on **Import Contacts** and upload a CSV file with email addresses.

## Broadcasts to Contacts

1. In the navigation panel, click on **Create Broadcast**.
2. Select a sender, and enter the subject and body of your email.
3. You can send a test email by clicking on **Test Email** to preview how your email will look.
4. Click on **Send Email** and confirm to send the email to all your contacts.


# SDKs
Source: https://docs.getsendbase.com/resources/sdks

Official AWS SDKs to integrate SES with your applications

<Columns>
  <Card title="JavaScript / TypeScript" icon="js" href="https://docs.aws.amazon.com/sdk-for-javascript/">
    AWS SDK for JavaScript
  </Card>

  <Card title="Python" icon="python" href="https://aws.amazon.com/sdk-for-python/">
    AWS SDK for Python
  </Card>

  <Card title="Java" icon="java" href="https://docs.aws.amazon.com/sdk-for-java/">
    AWS SDK for Java
  </Card>

  <Card title="Go" icon="golang" href="https://docs.aws.amazon.com/sdk-for-go/">
    AWS SDK for Go
  </Card>

  <Card title="Ruby" icon="gem" href="https://docs.aws.amazon.com/sdk-for-ruby/">
    AWS SDK for Ruby
  </Card>

  <Card title="PHP" icon="php" href="https://docs.aws.amazon.com/sdk-for-php/">
    AWS SDK for PHP
  </Card>

  <Card title=".NET" icon="code" href="https://docs.aws.amazon.com/sdk-for-net/">
    AWS SDK for .NET
  </Card>

  <Card title="Rust" icon="rust" href="https://docs.aws.amazon.com/sdk-for-rust/">
    AWS SDK for Rust
  </Card>
</Columns>