About The Retention.com API

This API is designed for simplicity and specific use cases.

We collect events in real-time. For real-time data delivery, we strongly recommend using webhooks.

The primary use of this API is for uploading daily suppression files when suppression is not available/supported with your native integration.

❗️

The API has certain limitations and should not be used for the following purposes:

• Uploading your initial suppression list (applies to new accounts)
• Uploading large lists (250,000 emails or more).

If any of the conditions mentioned above apply to your situation, please proceed by manually uploading your CSV file via the Retention.com dashboard. Click here to learn more.

📘

Your daily suppression files should only include contacts newly added to your list in the last 24-48 hours using the timestamp that represents when they were first added to your list. We recommend 48 hours in the event of an outage in your ESP platform.

API Authentication

• API Authentication: We use an API Key and API ID for authenticating requests. These keys can be created from within the Retention.com dashboard here (under My Account > API Details). For detailed instructions on how to get your credentials, please see the authentication section.

To be as flexible as possible, we allow passing the Key/ID in either the request header, body, or as a query parameter.

• Via Header: When sending the authentication tokens in the header they would have the format 'api-id' and 'api-key'.
• Via Params/Body: When sending the authentication tokens in the body or are parameters, they would be in the format 'api_id' and 'api_key'.

Example:

The api_id/api-id takes the form of a string such as: '430cc832fe7cd707b1320b8c6a'.

The api_key/api-key takes the form of a string such as: '21572420268b05fb52'.

API Limits

Our APIs are not designed for high-frequency querying; fetching data every 10 minutes or more frequently is not recommended.

Rate Limits:

Requests: You can make up to 5 requests per day, with each request handling approximately 50,000 emails.

Understanding the 24-Hour Rule:
What does "day" mean?

Our system implements a rolling 24-hour window to monitor your upload activity. This means the limit checks the number of files you've uploaded in the last 24 hours.

How it works:

If you have uploaded 5 files within any 24-hour period, you will need to wait until some of those files are older than 24 hours before you can upload again.

Example:

Suppose you uploaded 5 files between 1 PM and 5 PM on a given day. You must wait until after 1 PM the following day to upload another file. At that point, your first file upload from the previous day will be over 24 hours old, allowing you to make a new upload. This mechanism ensures a continuous check on your upload activity within the last 24 hours.

❗️

We implement API throttling to ensure optimal performance and resource management. If the default limits do not meet your specific requirements, please contact your R! representative for further details on our throttle limits and potential solutions.

---

System Monitoring

The systems use AI monitoring for health, stability, and to track abnormalities. The AI can block an account if it determines there's a threat to the system or if the API is being used improperly or abnormally. This is mostly due to the fact that the only call that should be used by most customers is for uploading a suppression list.

Data Format

Data is returned as a JSON string. You can review each API call for examples.

We're here to help!

If you get stuck, shoot us an email or use the blue icon on the bottom right of any page when logged into your Retention.com account to reach out to us.