Personalized Newsletter App Overview

This page gives an overview of the newsletter app for developer reference. What devs will build, the reference repository, high-level architecture and prerequisites.

This demo shows how to build personalized content experiences using Humanity Protocol's Connect SDK. Users authenticate with Humanity Protocol, and the app extracts their connected social accounts and verified credentials to personalize their news feed.

See the final product: https://demo.humanity.org/newsletter-demo

What You Will Build

By the end of this walkthrough, you will have a fully functional personalized newsletter application that:

• ✅ Authenticates users via Humanity Protocol OAuth 2.0 with PKCE

• ✅ Detects social connections (LinkedIn, Twitter/X, Discord, GitHub, Telegram)

• ✅ Verifies credentials using preset verification (connected accounts, travel preferences)

• ✅ Personalizes content based on user's digital identity

• ✅ Fetches and categorizes news from external APIs

• ✅ Provides real-time dev console showing API calls and responses

• ✅ Stores user preferences and news articles in MongoDB

• ✅ Runs automated sync jobs for content updates

Repository

The complete source code for this demo is available at:

https://github.com/humanity-org/hp-dev-api-docs/tree/main/examples/newsletter-app

High-Level Architecture

┌──────────────────────────────────────────────────────────────────┐
│                         Your Next.js App                         │
│                                                                  │
│  ┌─────────────────┐                                             │
│  │  Login Page     │  User clicks "Sign in with Humanity"        │
│  │  (Frontend)     │                                             │
│  └────────┬────────┘                                             │
│           │                                                      │
│           ▼                                                      │
│  ┌─────────────────┐         ┌──────────────────────┐            │
│  │  /api/auth/     │────────▶│  Humanity Protocol   │           │
│  │  login          │         │  SDK                 │            │
│  │                 │◀────────│  (OAuth + Presets)   │           │
│  └─────────────────┘         └──────────────────────┘            │
│           │                                                      │
│           ▼                                                      │
│  ┌─────────────────┐         User authorizes                     │
│  │  /callback      │         on Humanity Protocol                │
│  │  (OAuth return) │                                             │
│  └────────┬────────┘                                             │
│           │                                                      │
│           ▼                                                      │
│  ┌─────────────────────────────────────────┐                     │
│  │  Extract User Data:                     │                     │
│  │  • Profile (email, wallet)              │                     │
│  │  • Social connections (LinkedIn, etc.)  │                     │
│  │  • Travel preferences (Query Engine)    │                     │
│  └────────┬────────────────────────────────┘                     │
│           │                                                      │
│           ▼                                                      │
│  ┌─────────────────┐         ┌──────────────┐                    │
│  │   Save User     │────────▶│   MongoDB    │                   │
│  │   + Signals     │         │              │                    │
│  └─────────────────┘         │  • Users     │                    │
│           │                  │  • News      │                    │
│           │                  │  • API Logs  │                    │
│           │                  └──────────────┘                    │
│           ▼                                                      │
│  ┌─────────────────┐         ┌──────────────┐                    │
│  │  Fetch News     │────────▶│  GNews API   │                   │
│  │  (Cron Job)     │◀────────│              │                   │
│  └─────────────────┘         └──────────────┘                    │
│           │                                                      │
│           ▼                                                      │
│  ┌─────────────────────────────────────────┐                     │
│  │  Personalize Feed:                      │                     │
│  │  • Match articles to user signals       │                     │
│  │  • LinkedIn → Professional content      │                     │
│  │  • Twitter → Social/trending            │                     │
│  │  • Discord → Community                  │                     │
│  │  • GitHub → Tech                        │                     │
│  └────────┬────────────────────────────────┘                     │
│           │                                                      │
│           ▼                                                      │
│  ┌─────────────────┐                                             │
│  │  Feed Page      │  Display personalized articles              │
│  │  + Dev Console  │  Show API logs                              │
│  └─────────────────┘                                             │
│                                                                  │
└──────────────────────────────────────────────────────────────────┘

What You Need Before Starting

1. Development Environment

• Node.js: v20.16.0 or later (LTS recommended)

• Package Manager: npm, yarn, or bun

• MongoDB: Docker (recommended) or local installation

• Git: For cloning the repository

Note for Windows Users We strongly recommend using WSL 2 for this tutorial.

2. Humanity Protocol Sandbox Access

1. Go to https://developers.sandbox.humanity.org

2. Sign in or create a developer account

3. Click "Create Application"

4. Give your app a name (e.g., "Newsletter Demo")

5. Set your Redirect URI to: http://localhost:5173/callback

6. Save and copy your:

   • Client ID (starts with app_)

   • Client Secret (starts with sk_)

3. External API Keys

GNews API (for news content):

• Sign up athttps://gnews.io

• Get your free API key (100 requests/day)

• Note: GNews is mandatory for this demo to function

4. MongoDB Setup

Install MongoDB locally following the instructions for your OS: https://www.mongodb.com/docs/manual/installation/

Alternative: Use Docker

If you prefer Docker or encounter system-level compatibility issues:

# Start MongoDB container
docker run -d -p 27017:27017 --name mongodb mongo:latest

# Verify it's running
docker ps

# Stop MongoDB when needed
docker stop mongodb

# Start MongoDB again
docker start mongodb

Your connection string will be: mongodb://localhost:27017