ESP Integration REST API

A REST API built with NestJS that enables users to connect their Mailchimp and GetResponse accounts to store API keys and retrieve audience/list data.

This project was built as a backend assessment and demonstrates a professional, scalable, and robust API architecture.

---

Features ✨

• Secure Credential Storage: Save and validate API keys for Mailchimp and GetResponse.
• Live Key Validation: API keys are immediately verified with the respective service provider upon submission.
• Data Retrieval: Fetch all audience lists (Mailchimp) or campaigns (GetResponse) from a connected account.
• Robust Error Handling: Centralized exception filter for consistent and predictable error responses.
• Input Validation: DTO-based validation for all incoming request bodies and query parameters.
• Security: Implements rate limiting to prevent abuse.
• Database Integration: Uses TypeORM with PostgreSQL, connecting to a cloud-hosted database.

---

Prerequisites

• Node.js (v16 or higher)
• npm or Yarn

---

🚀 Installation & Setup

1. Clone the repository:

   git clone https://github.com/YOUR_USERNAME/YOUR_REPO_NAME.git
   cd YOUR_REPO_NAME

2. Install dependencies:

   npm install

3. Set up environment variables: This project connects to a cloud-hosted PostgreSQL database (e.g., from Neon).

   Create a .env file in the root of the project by copying the example file:

   cp .env.example .env

   You will need to add your database connection string to this file for local development.

   Your .env file should look like this:

   # Application Port
   PORT=3000
   
   # PostgreSQL Connection URL from your database provider
   DATABASE_URL="postgres://user:password@ep-ancient-sound-123456.us-east-2.aws.neon.tech/dbname?sslmode=require"

---

🏃 Running the Application

To run the application in development mode with live-reloading:

npm run start:dev

The API will be available at http://localhost:3000.

---

☁️ Deployment

This application is configured for deployment on cloud hosting services like Render. It follows a modern architecture using a stateless web service connected to a managed, external database.

The live, deployed version can be accessed at: [PASTE YOUR RENDER URL HERE]

---

↔️ API Endpoints

The global prefix /api is applied to all endpoints.

Integrations

Method	Endpoint	Description
POST	/integrations/esp	Saves and validates a new ESP API key.
GET	/integrations/esp/lists	Retrieves all lists from a connected ESP account.

POST /api/integrations/esp

Saves and validates an API key for either Mailchimp or GetResponse.

Request Body:

{
  "esp_name": "mailchimp",
  "api_key": "YOUR_MAILCHIMP_API_KEY-us21"
}

Success Response (201 Created):

{
  "esp_name": "mailchimp",
  "api_key": "YOUR_MAILCHIMP_API_KEY-us21",
  "id": "a1b2c3d4-e5f6-g7h8-i9j0-k1l2m3n4o5p6"
}

GET /api/integrations/esp/lists

Fetches all lists/campaigns for a given ESP.

Query Parameters:

• esp_name (string, required): The name of the ESP. Must be either mailchimp or getresponse.

Example URL: http://localhost:3000/api/integrations/lists?esp_name=mailchimp

Success Response (200 OK):

[
  {
    "id": "mc_list_id_1",
    "name": "Newsletter Subscribers"
  },
  {
    "id": "mc_list_id_2",
    "name": "Beta Testers"
  }
]

---

🗃️ Database Schema

The application uses a single table, integrations, to store the credentials. The schema is defined by the Integration entity in a PostgreSQL database.

Table: integrations

Column	Type	Constraints	Description
id	uuid	Primary Key	Auto-generated unique identifier.
esp_name	varchar	Not Null	The name of the ESP (mailchimp or getresponse).
api_key	varchar	Not Null, Unique	The API key for the ESP.