Linkpop Email

LinkPop Private Email

Private email server for agency gigworkers, creators, and marketers who manage multiple social media accounts. Create unlimited disposable email addresses at @linkpop.site for platform signups, account management, and online services — without risking your primary inbox.

Why LinkPop Mail?

Managing multiple social media accounts means juggling dozens of email addresses. One platform ban can cascade across every account tied to your personal Gmail. LinkPop Mail solves this:

• Unlimited disposable mailboxes — Spin up anything@linkpop.site in seconds for Instagram, TikTok, Twitter, or any platform signup
• Built-in password manager — Store login credentials scoped to each mailbox
• Built-in 2FA authenticator — Generate TOTP codes without a separate app, with QR code/webcam scanning
• Shareable standalone mailbox links — Hand off password-protected mailbox access to clients or team members via a standalone URL
• Email attachments — Private S3 storage with presigned URL access
• Auto-forward & webhooks — Real-time notifications for incoming emails (whitelisted users)
• API access — Full REST API for programmatic mailbox and email management

Pricing

URLs

Authentication

OTP Login (Web Users)

1. POST /auth/send-otp with { "email": "user@example.com" } — sends a 6-digit OTP
2. POST /auth/verify-otp with { "email": "user@example.com", "otp": "123456" } — returns JWT token + user profile

API Key (Programmatic Access)

After login, users have an API key in their settings. Pass it via header:

Authorization: Bearer <base64(user_id:secret)>

Rotate keys: POST /auth/rotate-api-key

Share Token (Standalone Mailbox)

Password-protected access via share token:

1. GET /share/:token/info — returns mailbox address
2. POST /share/:token/auth with { "password": "..." } — returns session token
3. Use session token for subsequent /share/:token/* requests

API Endpoints

Auth (/auth)

Mailboxes (/mailboxes)

Note: Address format is username@linkpop.site (production) or username.staging@linkpop.site (staging). A random 12-character share password is auto-generated on creation.

Emails (/emails)

Passwords (/passwords)

TOTP / 2FA (/totp)

Shared Mailbox (/share/:token)

Password-protected standalone access. All endpoints require prior auth via POST /share/:token/auth.

Admin (/admin)

Requires X-Admin-Key header matching SUPERADMIN_KEY env var.

Webhooks (/webhooks)

Data Models

User

interface User {
  user_id: string;
  email: string;
  tier: "FREE_TIER" | "PAID_TIER" | "UNLIMITED_TIER";
  api_key_id: string;
  api_key_secret: string; // hashed
  monthly_email_count: number;
  monthly_email_reset: string; // ISO date
  created_at: string;
  updated_at: string;
}

Mailbox

interface Mailbox {
  user_id: string;
  address: string; // e.g. "myname@linkpop.site"
  label?: string;
  share_token?: string;
  share_password?: string; // hashed, auto-generated 12 chars
  webhook_url?: string; // requires whitelist
  auto_forward?: string; // requires whitelist
  created_at: string;
  updated_at: string;
}

Email

interface Email {
  address: string; // mailbox address
  email_id: string;
  from: string;
  to: string;
  subject: string;
  text_body?: string;
  html_body?: string;
  attachments?: Attachment[];
  read: boolean;
  timestamp: string;
}

interface Attachment {
  id: string;
  filename: string;
  content_type: string;
  size: number;
  s3_key: string;
}

Password Entry

interface PasswordEntry {
  password_id: string;
  user_id: string;
  mailbox_address: string;
  website: string;
  username: string;
  password: string; // encrypted
  notes?: string;
  created_at: string;
  updated_at: string;
}

TOTP Entry

interface TOTPEntry {
  totp_id: string;
  user_id: string;
  mailbox_address: string;
  label: string;
  secret: string;
  issuer?: string;
  algorithm?: string;
  digits?: number;
  period?: number;
  created_at: string;
}

Rate Limits by Tier

Whitelist System

Certain features require admin whitelisting:

• Send emails — POST /emails/send
• Forward emails — POST /emails/forward
• Auto-forward — Setting auto_forward on a mailbox
• Webhooks — Setting webhook_url on a mailbox

Whitelist can be granted at two levels:

• User level: user:<user_id> — applies to all mailboxes
• Mailbox level: mailbox:<address> — applies to specific mailbox only

Architecture

• Frontend: React 18 + TypeScript + TailwindCSS + Zustand
• Backend: AWS Lambda (Node.js 20) + Express.js
• Database: DynamoDB (single table design, 3 GSIs)
• Storage: S3 (private attachments with presigned URLs, 365-day TTL)
• Email: Resend API (inbound webhook + outbound sending)
• Infrastructure: AWS CDK, CloudFront + S3 (frontend), API Gateway (backend)
• Domain: linkpop.site via Route53 + ACM SSL

Stage Isolation

• Staging: Emails use *.staging@linkpop.site, frontend at mail-staging.cloud.linkpop.site
• Production: Emails use *@linkpop.site, frontend at mail.cloud.linkpop.site
• Resend webhook filters by stage suffix to prevent cross-stage contamination

Usage Examples

Create a Mailbox

const API = "https://mail-staging.cloud.linkpop.site/api";
const TOKEN = "your-jwt-token";

const res = await fetch(`${API}/mailboxes`, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: `Bearer ${TOKEN}`,
  },
  body: JSON.stringify({
    address: "mycampaign",
    label: "Q1 Marketing Campaign",
  }),
});

const mailbox = await res.json();
// mailbox.address = "mycampaign.staging@linkpop.site"
// mailbox.share_token = "abc123..." (for standalone link)
// mailbox.share_password = "xK9m2..." (auto-generated)

List Emails

const emails = await fetch(`${API}/emails/mailbox/mycampaign.staging@linkpop.site`, {
  headers: { Authorization: `Bearer ${TOKEN}` },
}).then((r) => r.json());

Store a Password

await fetch(`${API}/passwords`, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: `Bearer ${TOKEN}`,
  },
  body: JSON.stringify({
    mailbox_address: "mycampaign.staging@linkpop.site",
    website: "instagram.com",
    username: "mycampaign_handle",
    password: "s3cur3p4ss",
    notes: "Client account for Q1 campaign",
  }),
});

Add a TOTP Entry

await fetch(`${API}/totp`, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: `Bearer ${TOKEN}`,
  },
  body: JSON.stringify({
    mailbox_address: "mycampaign.staging@linkpop.site",
    uri: "otpauth://totp/Instagram:mycampaign?secret=JBSWY3DPEHPK3PXP&issuer=Instagram",
  }),
});

Access Shared Mailbox

const SHARE_URL = "https://mail-staging.cloud.linkpop.site/api/share/abc123token";

// 1. Get mailbox info
const info = await fetch(`${SHARE_URL}/info`).then((r) => r.json());
// info.address = "mycampaign.staging@linkpop.site"

// 2. Authenticate
const auth = await fetch(`${SHARE_URL}/auth`, {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ password: "xK9m2..." }),
}).then((r) => r.json());

// 3. List emails
const emails = await fetch(`${SHARE_URL}/emails`, {
  headers: { Authorization: `Bearer ${auth.token}` },
}).then((r) => r.json());

Error Handling

Error response format:

{
  "error": "Error message describing what went wrong"
}

Deployment

npm run install:all    # Install all dependencies
npm run build:api      # Build Lambda API
npm run build:web      # Build React frontend
npm run deploy:staging # Deploy to staging via CDK
npm run deploy:production # Deploy to production via CDK

Deployment outputs are written to deployment.staging.json and deployment.production.json.