Introduction

Watch a quick video walkthrough of the setup

Amazon SES Identities

A verified SES Identity is an email address or domain that you have verified in AWS SES. To use Pendable, you will first need to make sure your AWS SES account is set up with at least one verified identity. Example page with verified identities is shown below.

You should see a list of your verified Domains and Email addresses under your SES Identities tab. If not, please follow the steps in AWS to create and verify an identity.

Amazon IAM Permissions

To use Pendable with Amazon SES, you need to create an IAM account in your AWS console with these permissions:

• AmazonSESFullAccess: This allows Pendable to send your platform emails using SES. It also allows Pendable to pull other relevant data like your send limit, reputation metrics, and SES Identities.
• AmazonSNSFullAccess: This allows Pendable to configure webhooks to receive email events like deliveries, clicks, and opens.
• CloudWatchFullAccess: This allows Pendable to create Bounce and Complaint alarms in Cloudwatch and get notified when your emails are closer to any of those limits. Pendable actively throttles your emails when your account nears warning state.

Below steps will help you create the IAM user called "Pendable-Email-API" for programmatic access in your AWS account:

Step 1:

Head over to your AWS IAM Panel to create a new IAM Role. In the Selected Trust Entity step select AWS account.

Then select Another AWS Account and enter 959716649733 in the Account ID. (This is Pendable's AWS Account ID)

Now in the External ID field, enter the value from your Pendable > SES Config > IAM External ID. That value should look like a 12 digit number broken down into 3 parts separated by dashes.

Note

XXXX-XXXX-XXXX is just a placeholder. Please use the correct value from your Pendable > SES Config > IAM External ID section.

Step 2:

In the next step to "Add Permissions", one-by-one select the three permissions "AmazonSESFullAccess", "AmazonSNSFullAccess", and "CloudWatchFullAccess".

Step 3:

Now in the final step, enter "Pendable-Email-API" for the Role Name and "IAM role to allow Pendable access to SES." in the Description. Make sure you have selected the three required permissions mentioned above and then hit "Create role".

Step 4:

Copy the ARN of the newly created role.

Step 5:

Now head over to Pendable and create a new SES Config.

Client Identifier is a unique name you can give to this SES Config.

Select the same AWS region as that of your Amazon SES. Also mark the "Is Default" and "Is Active" as Yes.

Now enter the ARN copied from Step 4 above.

SES Sandbox Mode

To use Pendable with Amazon SES and send emails to live contacts, you will need to request SES to move your account out of the Sandbox mode.

Make sure you provide SES with all the required information to process your production access request. Below are some important points in your application to SES:

• Make sure you mention that you use Pendable to automatically processes bounces, complaints, and unsubscribes for you.
• Also make sure you own your domain, that it is added as a Verified Identity in SES and provide a link to your website.

Active Bounce and Complaint monitoring

Pendable uses cloudwatch alarms on AWS to get notified when your Bounce and/or Complaint rate enter warning state. This helps in active resolution as Pendable is able to throttle or stop sending emails to SES and give SES time to heal. We monitor your SES reputation metrics closely and only resume sending and ease throttling when we see your SES account is sufficiently healed. You will also receive an email from Pendable notifying you of the spike and subsequent resolution automatically.

In the event of a hard Bounce or Complaint, we add that email address to your account's suppression list and avoid sending any future emails to that id.

Tracking Email Events (Opens, Clicks)

You need to use an "html_body" in your API call in order to receive Open and Click events. Each email in Pendable shows a timeline view of these events. Additionally, we use the email delivery events to keep your contact list healthy.

Priority Queues

With Pendable, you can specify a "Priority" value for each email. This value is an integer between 1 and 100 with 1 being the highest priority and 100 being the lowest. Default priority of 50 is applied to an email if you do not specify the priority value for it. Using priorities, you can prioritize critical emails like password-resets, sign-up confirmations, etc. over other medium and low priority ones like marketing.

Pendable handles priority across your current and future scheduled emails. Say you have some emails scheduled to go out later today, when that time comes, those emails will be queued up and merged with the execution pool of emails then - all these emails will be dynamically ordered based on their priorities and sent for execution accordingly.

Resending Emails

Pendable saves a log of emails you send. The number of emails we save depends on your subscription plan. This log of emails allows you to search an email and view its entire events log like Delivery, Open, Click, Bonce, etc. You can also re-trigger an email upon a customer request. Pendable makes it easy to resend and analyze emails from logs.

Authentication

Pendable uses a Bearer token based authentication. You can generate your Bearer token from the "Tokens" section under your Pendable account.

In case your API call does not have a valid Authorization header with a valid Bearer token, you will receive a 403 (Forbidden) error response.

Rate Limiting

You may receive a status 429 Too Many Attempts if you exceed the default rate limit based on your tier. Pendable sends response headers x-ratelimit-limit and x-ratelimit-remaining to help your configure the correct thresholds on your end.

Sending Emails

You can send an email by making a POST request to our /emails endpoint. Your POST request should have the "Authorization" header with the "Bearer" token. The POST request's body should contain a JSON message with the required parameters.

                            
{
    "client_email_id": "your-id-1234",
    "from": "[email protected]",
    "to": "[email protected]",
    "cc": [
        "[email protected]",
        "[email protected]"
    ],
    "bcc": [
        "[email protected]",
        "[email protected]"
    ],
    "reply_to": "[email protected]",
    "subject": "Your first email from Pendable",
    "html_body": "Html content of your email.",
    "text_body": "Text content of your text-only email.",
    "schedule_send_at": "2023-04-22T22:41:42+00:00", // ISO8601_EXPANDED format
    "custom_fields": {
        "internal_id": 123,
        "project_code": "abc"
    },
    "tags": [
        "high-value",
        "transactional"
    ],
    "priority": 75,
    "config_identifier": "my-default-config"
}
                                
                            

The from, to, cc, bcc fields are all able to accept emails in the format [email protected] or the Jon Doe <[email protected]>.

You can provide an html_body for HTML-formatted messages, a text_body for plain text, or include both for multipart messages. Multipart messages send HTML with a text version for clients that don't support HTML. Most email clients will prefer the html_body.

• from [required] needs to be a single verified email id under your AWS SES account.
• to [required] needs to be a single recipient email id.
• cc [optional] needs to be a list of one or more email ids.
• bcc [optional] needs to be a list of one or more email ids.
• reply_to [optional] needs to be a single email id.
• subject [required] is a text subject for the email.
• html_body [optional if text_body provided] is the html body for the email. This is recommended over text_body.
• text_body [optional if html_body provided] is the text body for the email. Note that html_body or text_body must be provided. The system will return an error if both are not provided.
• client_email_id [optional] is the unique id from your system - this field is used for de-duplication on Pendable. If we receive another request with the same client_email_id, our system will throw an error and reject the duplicate request.
• schedule_send_at [optional] needs to be a future date in the ISO8601_EXPANDED format. Eg: "2024-11-22T07:27:10+00:00"
• priority [optional] must be between 1 and 100. 1 is the highest priority while 100 is the lowest. By default, we set the priority to 50 if you do not pass it as a param.
• config_identifier [optional] You can save more than one SES config on Pendable - each has a unique name that you assign. You can pass config_identifier with your request to choose which SES config you want to use for sending an email. Your default config is used if this parameter is not supplied.
• custom_fields [optional] needs to be a dictionary of key-value pairs. You can leverage these custom fields to slice and dice data and reports on Pendable.
• tags [optional] needs to be a list of text values. You can leverage these tags to slice and dice data and reports on Pendable.
• The message must be sent from a verified email address or domain.
• The maximum message size is 10 MB.
• Based on AWS's limits, you can have a maximum of 50 recipients per message. A recipient is any to, cc, or bcc address. If you need to send an email message to a larger audience, you can divide your recipient list into groups of 50 or fewer, and then call the API to send the message to each group.

Success Response

If your request was accepted by Pendable, you will receive a success response (200 OK) with a pendable_id parameter in the response. This is the unique id for your email in Pendable. You may choose to save this on your end for reference.

Sample response:

                            
{
    "pendable_id": "0bcb2124-1f54-4c4a-9944-0b546c28be33",
    "pendable_received_on": "2024-11-20T07:27:10+00:00"
}
                            
                        

Error Response

If your request was not accepted by Pendable, you will receive an error with a response code of 422 (Unprocessable Entity) and a "detail" attribute with the errors.

Sample error response - missing "to" and "subject" fields:

                            
{
    "detail": [
        {
            "loc": [
                "body",
                "to"
            ],
            "msg": "field required",
            "type": "value_error.missing"
        },
        {
            "loc": [
                "body",
                "subject"
            ],
            "msg": "field required",
            "type": "value_error.missing"
        }
    ]
}
                            
                        

Tags & Custom Fields

With each email, you can specify a list of tags and a list of custom_fields

Tags are simple text strings while custom_fields are key-value pairs. You can view the tags and custom_fields associated with an email on the email details page.

You can also filter reports and charts by tags and custom_fields on the Pendable dashboard to measure engagement across your different audience segments.

Attachments

Pendable currently does not support emails with attachments. It is a feature we plan to add in the future.

PHP Laravel Mailer: https://github.com/Pendable/laravel-mailer

PHP Symfony Mailer: https://github.com/Pendable/symfony-mailer

Billing Related

Does Pendable's monthly charge include Amazon SES costs?

No, Pendable's monthly charge does not include any SES costs. You would continue to pay for SES as you do today while we will bill you separately each month based on your Pendable subscription plan.

When will my card be charged each month?

Your card will be charged monthly on the date your subscription plan started.

What is the overage charge on my bill?

Your monthly plan provides you with a certain base number of emails you can send. When you exceed that base number, we charge you an overage for the excess number of emails you sent. Eg: if you have subscribed to the 128,000 email plan and you end up sending 150,000 emails, you would be charged an overage fee of $13.20 (based on $0.6 per thousand emails for 22,000 overage).

What happens when I upgrade/downgrade in the middle of a billing cycle?

We apply the appropriate proration logic depending on whether it is an upgrade or a downgrade. We calculate the billing amount proportionally based on the number of days covered by your old and new plans. You are charged solely for what you've used in a billing period.

What happens when the emails quota runs out?

When we see your usage nearing your monthly cap, we alert you via multiple email notifications. If you choose to ignore those and decide not to upgrade, then we cannot service your new incoming requests once you exhaust your quota.

How can I cancel my account?

You can cancel your billing plan by heading to the billing dashboard and cancelling your subscription. To delete all your data, you can get in touch with us at [email protected]

Account Related

Is there a limit to how many contacts I can have?

There is no limit on the number of contacts you can have in your account. You are only limited by the email quotas.

Storage Related

What is the Email Storage Limit?

Pendable stores a copy of all emails you send via its API. These emails are then accessible to you for searching and debugging or looking at the what user actions were performed on those (like open, click, etc). We store only the last X emails under your account, where X is the Email Storage Limit based on your subscription plan.