Skip to main content

Actions

The AWS SES connector exposes the following clients:

Available clients:

ClientPurpose
ClientSend email and manage identities, contact lists, and templates in an Amazon SES account

Client​

The Client provides operations for sending email and managing the identities, contact lists, and templates that an Amazon SES account uses.

Configuration​

ConnectionConfig

FieldTypeDefaultDescription
authauth:AuthConfigRequiredAuthentication configuration: static credentials, AWS profile, STS assume-role, web identity (OIDC), IAM Identity Center (SSO), external credential process, or the default provider chain
regionaws:Region|stringRequiredAWS region: an aws:Region enum member or a plain region string (e.g., "us-east-1") for regions not yet in the enum
endpointaws:EndpointConfigOptionalOptional endpoint options: FIPS/dualstack variants, or a custom endpoint override (e.g. VPC interface endpoints)

The client also accepts the standard Ballerina HTTP client options (timeout, retryConfig, secureSocket, proxy, and the rest of http:ClientConfiguration), which are omitted here.

Initializing the client​

import ballerinax/aws.ses;

ses:ConnectionConfig config = {
    auth: {
        accessKeyId: "<AWS_ACCESS_KEY_ID>",
        secretAccessKey: "<AWS_SECRET_ACCESS_KEY>"
    },
    region: "us-east-1"
};
ses:Client client = check new (config);

Operations​

Email sending​

sendEmail

Sends an email message. The message may be simple — a subject and a body that Amazon SES assembles — raw, a MIME message carrying its own headers and any attachments, or template, whose personalization tags Amazon SES replaces with the values supplied.

Parameters:

NameTypeRequiredDescription
requestSendEmailInputYesThe details of the message to send

Returns: SendEmailOutput|Error

Sample code:

ses:SendEmailOutput result = check client->sendEmail({
    fromEmailAddress: "[email protected]",
    destination: {toAddresses: ["[email protected]"]},
    replyToAddresses: ["[email protected]"],
    content: {
        simple: {
            subject: {data: "Your order has shipped", charset: "UTF-8"},
            body: {
                html: {data: "<html><body><p>It is on its way.</p></body></html>", charset: "UTF-8"},
                text: {data: "It is on its way.", charset: "UTF-8"}
            }
        }
    }
});

Sample response:

{
  "messageId": "0102018e1234abcd-12345678-abcd-1234-abcd-1234567890ab-000000"
}
sendBulkEmail

Composes a templated email message to many destinations. Each entry carries its own recipients and its own replacement values; the result carries one outcome per entry, in the order the entries were given.

Parameters:

NameTypeRequiredDescription
requestSendBulkEmailInputYesThe details of the messages to send

Returns: SendBulkEmailOutput|Error

Sample code:

ses:SendBulkEmailOutput result = check client->sendBulkEmail({
    fromEmailAddress: "[email protected]",
    defaultContent: {
        template: {
            templateName: "OrderShipped",
            templateData: "{\"name\":\"there\",\"orderId\":\"unknown\"}"
        }
    },
    bulkEmailEntries: [
        {
            destination: {toAddresses: ["[email protected]"]},
            replacementEmailContent: {
                replacementTemplate: {
                    replacementTemplateData: "{\"name\":\"Sam\",\"orderId\":\"SO-4418\"}"
                }
            }
        }
    ]
});

Sample response:

{
  "bulkEmailEntryResults": [
    {
      "status": "SUCCESS",
      "messageId": "0102018e1234abcd-12345678-abcd-1234-abcd-1234567890ab-000000"
    }
  ]
}
sendCustomVerificationEmail

Adds an email address to the account's identities and sends it a custom verification email. A custom verification email template has to exist before this operation can be used.

Parameters:

NameTypeRequiredDescription
requestSendCustomVerificationEmailInputYesThe details of the verification email to send

Returns: SendEmailOutput|Error

Sample code:

ses:SendEmailOutput result = check client->sendCustomVerificationEmail({
    emailAddress: "[email protected]",
    templateName: "SupplierVerification"
});

Sample response:

{
  "messageId": "0102018e5678efgh-87654321-efgh-5678-efgh-0987654321ba-000000"
}

Email identity management​

createEmailIdentity

Starts the process of verifying an email identity — an email address or a domain that email is sent from. An identity has to be verified before it can be used as a sending address. Verifying a domain without supplying dkimSigningAttributes returns the DKIM tokens to add to the domain's DNS configuration.

Parameters:

NameTypeRequiredDescription
requestCreateEmailIdentityInputYesThe details of the email identity to create

Returns: CreateEmailIdentityOutput|Error

Sample code:

ses:CreateEmailIdentityOutput identity = check client->createEmailIdentity({
    emailIdentity: "[email protected]"
});

Sample response:

{
  "identityType": "EMAIL_ADDRESS",
  "verifiedForSendingStatus": false,
  "dkimAttributes": {
    "signingAttributesOrigin": "AWS_SES",
    "signingEnabled": false,
    "status": "NOT_STARTED",
    "tokens": []
  }
}
getEmailIdentity

Returns information about an identity, including its verification status, its sending authorization policies, its DKIM authentication status, and its custom MAIL FROM settings.

Parameters:

NameTypeRequiredDescription
emailIdentitystringYesThe email address or domain of the identity

Returns: EmailIdentityDetails|Error

Sample code:

ses:EmailIdentityDetails identity = check client->getEmailIdentity("[email protected]");

Sample response:

{
  "identityType": "EMAIL_ADDRESS",
  "verificationStatus": "SUCCESS",
  "verifiedForSendingStatus": true,
  "dkimAttributes": {
    "signingAttributesOrigin": "AWS_SES",
    "signingEnabled": true,
    "status": "SUCCESS",
    "tokens": ["token1", "token2", "token3"]
  },
  "mailFromAttributes": {
    "mailFromDomain": "",
    "mailFromDomainStatus": "NOT_STARTED",
    "behaviorOnMxFailure": "USE_DEFAULT_VALUE"
  },
  "feedbackForwardingStatus": true
}
listEmailIdentities

Lists the email identities associated with the AWS account, verified and unverified alike, fetching each page as the previous one is consumed.

Parameters:

NameTypeRequiredDescription
requestListEmailIdentitiesInputNoThe details of the identities to list (default: {})

Returns: stream<IdentityInfo, Error?>

Sample code:

stream<ses:IdentityInfo, ses:Error?> identities = client->listEmailIdentities();
check from ses:IdentityInfo identity in identities
    do {
        // process identity
    };

Sample response:

[
  {
    "identityName": "[email protected]",
    "identityType": "EMAIL_ADDRESS",
    "sendingEnabled": true,
    "verificationStatus": "SUCCESS"
  },
  {
    "identityName": "example.com",
    "identityType": "DOMAIN",
    "sendingEnabled": true,
    "verificationStatus": "SUCCESS"
  }
]
deleteEmailIdentity

Deletes an email identity.

Parameters:

NameTypeRequiredDescription
emailIdentitystringYesThe email address or domain of the identity to delete

Returns: Error?

Sample code:

check client->deleteEmailIdentity("[email protected]");

Contact list management​

createContactList

Creates a contact list.

Parameters:

NameTypeRequiredDescription
requestCreateContactListInputYesThe details of the contact list to create

Returns: Error?

Sample code:

check client->createContactList({
    contactListName: "ProductNewsletter",
    description: "Monthly product newsletter",
    topics: [
        {
            topicName: "product-updates",
            displayName: "Product updates",
            description: "News about product releases",
            defaultSubscriptionStatus: ses:OPT_OUT
        }
    ]
});
updateContactList

Updates the metadata of a contact list. This operation does a complete replacement of the description and the topics.

Parameters:

NameTypeRequiredDescription
contactListNamestringYesThe name of the contact list
requestUpdateContactListInputYesThe details to replace the contact list's metadata with

Returns: Error?

Sample code:

check client->updateContactList("ProductNewsletter", {
    description: "Weekly product news",
    topics: [
        {
            topicName: "product-updates",
            displayName: "Product updates",
            description: "News about product releases",
            defaultSubscriptionStatus: ses:OPT_OUT
        }
    ]
});
getContactList

Returns the metadata of a contact list. It does not return any information about the contacts in the list.

Parameters:

NameTypeRequiredDescription
contactListNamestringYesThe name of the contact list

Returns: ContactListDetails|Error

Sample code:

ses:ContactListDetails contactList = check client->getContactList("ProductNewsletter");

Sample response:

{
  "contactListName": "ProductNewsletter",
  "description": "Monthly product newsletter",
  "topics": [
    {
      "topicName": "product-updates",
      "displayName": "Product updates",
      "description": "News about product releases",
      "defaultSubscriptionStatus": "OPT_OUT"
    }
  ],
  "createdTimestamp": 1700000000.0,
  "lastUpdatedTimestamp": 1700000000.0
}
listContactLists

Lists the contact lists available to the account, fetching each page as the previous one is consumed.

Parameters:

NameTypeRequiredDescription
requestListContactListsInputNoThe details of the contact lists to list (default: {})

Returns: stream<ContactList, Error?>

Sample code:

stream<ses:ContactList, ses:Error?> contactLists = client->listContactLists();
check from ses:ContactList contactList in contactLists
    do {
        // process contactList
    };

Sample response:

[
  {
    "contactListName": "ProductNewsletter",
    "lastUpdatedTimestamp": 1700000000.0
  }
]
deleteContactList

Deletes a contact list and every contact on it.

Parameters:

NameTypeRequiredDescription
contactListNamestringYesThe name of the contact list

Returns: Error?

Sample code:

check client->deleteContactList("ProductNewsletter");

Contact management​

createContact

Creates a contact — an end user receiving the email — and adds them to a contact list.

Parameters:

NameTypeRequiredDescription
contactListNamestringYesThe name of the contact list to add the contact to
requestCreateContactInputYesThe details of the contact to create

Returns: Error?

Sample code:

check client->createContact("ProductNewsletter", {
    emailAddress: "[email protected]",
    topicPreferences: [{topicName: "product-updates", subscriptionStatus: ses:OPT_IN}]
});
updateContact

Updates a contact's preferences for a list. A topicPreferences value replaces the contact's whole preference list, so it has to carry every existing preference and not only the ones being changed — Amazon SES removes any that are omitted.

Parameters:

NameTypeRequiredDescription
contactListNamestringYesThe name of the contact list the contact belongs to
emailAddressstringYesThe contact's email address
requestUpdateContactInputYesThe details to update the contact with

Returns: Error?

Sample code:

ses:ContactDetails contact = check client->getContact("ProductNewsletter", "[email protected]");
ses:TopicPreference[] preferences = from ses:TopicPreference preference in contact.topicPreferences ?: []
    select preference.topicName == "product-updates"
        ? {topicName: preference.topicName, subscriptionStatus: ses:OPT_OUT}
        : preference;

check client->updateContact("ProductNewsletter", "[email protected]", {
    topicPreferences: preferences
});
getContact

Returns a contact from a contact list.

Parameters:

NameTypeRequiredDescription
contactListNamestringYesThe name of the contact list the contact belongs to
emailAddressstringYesThe contact's email address

Returns: ContactDetails|Error

Sample code:

ses:ContactDetails contact = check client->getContact("ProductNewsletter", "[email protected]");

Sample response:

{
  "emailAddress": "[email protected]",
  "contactListName": "ProductNewsletter",
  "topicPreferences": [
    {
      "topicName": "product-updates",
      "subscriptionStatus": "OPT_IN"
    }
  ],
  "topicDefaultPreferences": [
    {
      "topicName": "product-updates",
      "subscriptionStatus": "OPT_OUT"
    }
  ],
  "unsubscribeAll": false,
  "createdTimestamp": 1700000000.0,
  "lastUpdatedTimestamp": 1700000000.0
}
listContacts

Lists the contacts of a contact list, fetching each page as the previous one is consumed.

Parameters:

NameTypeRequiredDescription
contactListNamestringYesThe name of the contact list
requestListContactsInputNoThe details of the contacts to list (default: {})

Returns: stream<Contact, Error?>

Sample code:

stream<ses:Contact, ses:Error?> contacts = client->listContacts("ProductNewsletter", {
    filter: {
        filteredStatus: ses:OPT_IN,
        topicFilter: {topicName: "product-updates", useDefaultIfPreferenceUnavailable: true}
    },
    pageSize: 50
});
check from ses:Contact contact in contacts
    do {
        // process contact
    };

Sample response:

[
  {
    "emailAddress": "[email protected]",
    "topicPreferences": [
      {
        "topicName": "product-updates",
        "subscriptionStatus": "OPT_IN"
      }
    ],
    "unsubscribeAll": false,
    "lastUpdatedTimestamp": 1700000000.0
  }
]
deleteContact

Removes a contact from a contact list.

Parameters:

NameTypeRequiredDescription
contactListNamestringYesThe name of the contact list the contact belongs to
emailAddressstringYesThe contact's email address

Returns: Error?

Sample code:

check client->deleteContact("ProductNewsletter", "[email protected]");

Email template management​

createEmailTemplate

Creates an email template, which lets one API call send a personalized message to each of many destinations.

Parameters:

NameTypeRequiredDescription
requestCreateEmailTemplateInputYesThe details of the email template to create

Returns: Error?

Sample code:

check client->createEmailTemplate({
    templateName: "OrderShipped",
    templateContent: {
        subject: "Order {{orderId}} has shipped",
        html: "<html><body><p>Hello {{name}}, order {{orderId}} is on its way.</p></body></html>",
        text: "Hello {{name}}, order {{orderId}} is on its way."
    }
});
updateEmailTemplate

Updates an email template. This operation does a complete replacement of the template's content.

Parameters:

NameTypeRequiredDescription
templateNamestringYesThe name of the template
requestUpdateEmailTemplateInputYesThe content to replace the template's with

Returns: Error?

Sample code:

check client->updateEmailTemplate("OrderShipped", {
    templateContent: {
        subject: "Your order is on its way",
        text: "Hello {{name}}, your order is on its way."
    }
});
getEmailTemplate

Returns the template of the given name, including its subject line, its HTML part, and its text part.

Parameters:

NameTypeRequiredDescription
templateNamestringYesThe name of the template

Returns: EmailTemplateDetails|Error

Sample code:

ses:EmailTemplateDetails template = check client->getEmailTemplate("OrderShipped");

Sample response:

{
  "templateName": "OrderShipped",
  "templateContent": {
    "subject": "Order {{orderId}} has shipped",
    "html": "<html><body><p>Hello {{name}}, order {{orderId}} is on its way.</p></body></html>",
    "text": "Hello {{name}}, order {{orderId}} is on its way."
  }
}
listEmailTemplates

Lists the email templates of the account in the current AWS Region, fetching each page as the previous one is consumed.

Parameters:

NameTypeRequiredDescription
requestListEmailTemplatesInputNoThe details of the templates to list (default: {})

Returns: stream<EmailTemplateMetadata, Error?>

Sample code:

stream<ses:EmailTemplateMetadata, ses:Error?> templates = client->listEmailTemplates();
check from ses:EmailTemplateMetadata template in templates
    do {
        // process template
    };

Sample response:

[
  {
    "templateName": "OrderShipped",
    "createdTimestamp": 1700000000.0
  }
]
deleteEmailTemplate

Deletes an email template.

Parameters:

NameTypeRequiredDescription
templateNamestringYesThe name of the template to delete

Returns: Error?

Sample code:

check client->deleteEmailTemplate("OrderShipped");

Custom verification email template management​

createCustomVerificationEmailTemplate

Creates a custom verification email template.

Parameters:

NameTypeRequiredDescription
requestCreateCustomVerificationEmailTemplateInputYesThe details of the custom verification email template to create

Returns: Error?

Sample code:

check client->createCustomVerificationEmailTemplate({
    templateName: "SupplierVerification",
    fromEmailAddress: "[email protected]",
    templateSubject: "Please confirm your email address",
    templateContent: "<html><body><p>Confirm your address.</p></body></html>",
    successRedirectionUrl: "https://example.com/verified",
    failureRedirectionUrl: "https://example.com/not-verified"
});
updateCustomVerificationEmailTemplate

Updates an existing custom verification email template.

Parameters:

NameTypeRequiredDescription
templateNamestringYesThe name of the custom verification email template to update
requestUpdateCustomVerificationEmailTemplateInputYesThe details to replace the template with

Returns: Error?

Sample code:

check client->updateCustomVerificationEmailTemplate("SupplierVerification", {
    fromEmailAddress: "[email protected]",
    templateSubject: "Confirm your email address",
    templateContent: "<html><body><p>Please confirm your address.</p></body></html>",
    successRedirectionUrl: "https://example.com/verified",
    failureRedirectionUrl: "https://example.com/not-verified"
});
getCustomVerificationEmailTemplate

Returns the custom verification email template of the given name.

Parameters:

NameTypeRequiredDescription
templateNamestringYesThe name of the custom verification email template to retrieve

Returns: CustomVerificationEmailTemplateDetails|Error

Sample code:

ses:CustomVerificationEmailTemplateDetails template = check client->getCustomVerificationEmailTemplate("SupplierVerification");

Sample response:

{
  "templateName": "SupplierVerification",
  "fromEmailAddress": "[email protected]",
  "templateSubject": "Please confirm your email address",
  "templateContent": "<html><body><p>Confirm your address.</p></body></html>",
  "successRedirectionUrl": "https://example.com/verified",
  "failureRedirectionUrl": "https://example.com/not-verified"
}
listCustomVerificationEmailTemplates

Lists the custom verification email templates of the account in the current AWS Region, fetching each page as the previous one is consumed.

Parameters:

NameTypeRequiredDescription
requestListCustomVerificationEmailTemplatesInputNoThe details of the templates to list (default: {})

Returns: stream<CustomVerificationEmailTemplateMetadata, Error?>

Sample code:

stream<ses:CustomVerificationEmailTemplateMetadata, ses:Error?> templates = client->listCustomVerificationEmailTemplates();
check from ses:CustomVerificationEmailTemplateMetadata template in templates
    do {
        // process template
    };

Sample response:

[
  {
    "templateName": "SupplierVerification",
    "fromEmailAddress": "[email protected]",
    "templateSubject": "Please confirm your email address",
    "successRedirectionUrl": "https://example.com/verified",
    "failureRedirectionUrl": "https://example.com/not-verified"
  }
]
deleteCustomVerificationEmailTemplate

Deletes an existing custom verification email template.

Parameters:

NameTypeRequiredDescription
templateNamestringYesThe name of the custom verification email template to delete

Returns: Error?

Sample code:

check client->deleteCustomVerificationEmailTemplate("SupplierVerification");
Last updated on
On this page
Was this page helpful?
Report an issue