Portfolio Build · Public GitHub Demo

Email Campaign & Delivery Tracking Platform

A production-style email marketing and delivery-analytics platform — campaign authoring, recipient list management, queued sending, webhook-driven delivery tracking (sent, delivered, opened, clicked, bounced, complained, unsubscribed) and campaign analytics — built with NestJS, MongoDB, React/TypeScript and AWS.

Repository

email-campaign-delivery-tracker

Author

R.M. — Arsi India Info

Category

Node.js · AWS · Webhooks · Background Processing

License

MIT (code) + Trademark Notice (brand)

1. Executive Summary

The platform lets an organization create an email campaign, send it to a recipient list, and track exactly what happened to every message: queued → sent → delivered → opened → clicked, with side branches for bounced, failed, marked as spam, and unsubscribed. It demonstrates backend engineering depth that a CRUD app cannot: asynchronous queue processing, inbound webhook ingestion with signature verification, idempotent event handling, and campaign-level analytics rollups — the exact skill set a Node.js/AWS backend role screens for.

Scope is deliberately kept to what a demo needs to prove the architecture: one email-sending provider integration (Amazon SES, with a provider-agnostic webhook layer that would also accept SendGrid/Mailgun/Postmark payloads), one organization per signed-in workspace, and synthetic seed data only (fictional company "NovaMail Retail Co.", fake contacts, no real email addresses are ever sent to in the demo — see §29 Docker section for the local mail-catcher setup).

2. Why This Is a Top-Tier Portfolio Project

Order-management and CRM demos are common; a correctly-modeled event-sourced delivery pipeline is not. This project is chosen specifically because it forces decisions a reviewer will recognize as production-grade:

3. Technology Stack

4. Repository & Folder Structure

email-campaign-delivery-tracker/
├── backend/                              # NestJS API + worker
│   └── src/
│       ├── main.ts                       # bootstrap, global pipes/filters/interceptors, Swagger mount
│       ├── worker.ts                     # separate entrypoint for the SQS consumer process
│       ├── config/                       # env schema (Joi), typed ConfigModule providers
│       ├── common/                       # cross-cutting: filters, interceptors, guards, decorators, pipes
│       │   ├── filters/http-exception.filter.ts
│       │   ├── interceptors/logging.interceptor.ts
│       │   ├── guards/jwt-auth.guard.ts
│       │   ├── guards/roles.guard.ts
│       │   └── decorators/current-user.decorator.ts
│       ├── database/                     # Mongoose connection module, index bootstrap script
│       ├── modules/
│       │   ├── auth/                     # login, refresh, register, guards, JWT strategy
│       │   ├── organizations/            # org profile, sender domain settings
│       │   ├── users/                    # team members, roles
│       │   ├── templates/                # reusable HTML email templates
│       │   ├── contacts/                 # contact lists + contacts + CSV import
│       │   ├── campaigns/                # campaign CRUD, schedule, send, analytics
│       │   ├── sending/                  # EmailService (SES adapter), SendQueue producer/consumer
│       │   ├── webhooks/                 # provider webhook ingestion, signature verification, dedup
│       │   ├── tracking/                 # public open-pixel + click-redirect + unsubscribe endpoints
│       │   ├── events/                   # append-only event log + analytics rollups
│       │   ├── suppressions/             # global suppression list
│       │   └── audit/                    # audit log writer + reader
│       └── shared/                       # DTOs, enums, interfaces shared across modules
│   └── test/                             # e2e (Supertest) specs, one per module
│
├── frontend/                             # React + TypeScript SPA
│   └── src/
│       ├── app/                          # router, providers, layout shell
│       ├── features/
│       │   ├── auth/
│       │   ├── dashboard/
│       │   ├── campaigns/                # list, wizard (create/edit), detail/analytics
│       │   ├── templates/
│       │   ├── contacts/                 # lists + contact tables + CSV import
│       │   ├── suppressions/
│       │   └── settings/
│       ├── components/                   # shared, presentational-only (Button, DataTable, StatCard, StateBadge...)
│       ├── lib/                          # apiClient (axios + interceptors), queryClient, formatters
│       └── types/                        # API response types, generated or hand-mirrored from DTOs
│
├── shared/                               # types/constants imported by BOTH frontend and backend (delivery-status enum, error codes)
│
├── infra/                                # deployment-related, kept out of application code
│   ├── docker/                           # Dockerfile.api, Dockerfile.worker, Dockerfile.web
│   ├── docker-compose.yml                # api + worker + mongo + mailhog + localstack, one command up
│   ├── aws/                              # CDK or Terraform for SQS/S3/SES/CloudWatch (documented, optional to run)
│   └── github-actions/                   # CI pipeline yaml
│
├── docs/                                 # see §32 — API docs, ERD, runbooks, screenshots
├── .github/
├── LICENSE                               # MIT
├── TRADEMARK.md                          # Arsi India Info name/logo notice — see §31
└── README.md

5. Coding Standards & Conventions

These rules apply uniformly across every module in §4 — they are what keeps a ten-module NestJS app reviewable rather than a pile of one-off controllers.

6. Organization Isolation & RBAC

Every account belongs to exactly one Organization (workspace). All campaign, template, contact and analytics data is scoped to `organizationId`, mirroring how a real ESP separates customers.

6.1 How an organization is established

1. Registering creates a new `Organization` and a first user with role OWNER.
2. The JWT access token embeds `{ sub: userId, organizationId, role }`.
3. A `JwtAuthGuard` decodes the token; an `OrgScopeInterceptor` attaches `organizationId` to the request context.
4. Every repository method extends `OrgScopedRepository`, which injects `{ organizationId }` into every `find`, `updateOne`, and `deleteOne` filter — a resource belonging to another organization is architecturally unreachable, not just permission-checked.

6.2 Roles

Enforced with a `@Roles(...)` decorator + `RolesGuard` read from the same JWT claim — no extra DB round-trip per request.

7. Database Schema (MongoDB)

7.1 Collection inventory

An audit_logs collection (§10) rounds this out to ten. Field sets are intentionally narrow — no custom-field builder, no multi-currency, no A/B testing framework; those are exactly the kind of enterprise features a portfolio demo should skip (see §2).

7.2 Representative schemas

// campaigns collection (Mongoose schema, abbreviated)
{
  organizationId: ObjectId,        // tenant scope — see §6
  name:           String,          // required, 3-120 chars
  subject:        String,          // required, 3-200 chars
  fromName:       String,
  fromEmail:      String,          // must match org's verified sender domain
  templateId:     ObjectId,         // ref: templates
  listIds:        [ObjectId],       // ref: contact_lists, min 1
  status:         String,          // DRAFT|SCHEDULED|SENDING|SENT|PAUSED|CANCELLED — §8
  scheduledAt:    Date,             // null for immediate send
  sentAt:         Date,
  stats: {                     // denormalized rollup, rebuilt from events (§7.3)
    queued: Number, sent: Number, delivered: Number, opened: Number,
    clicked: Number, bounced: Number, complained: Number,
    failed: Number, unsubscribed: Number
  },
  version:        Number,           // optimistic lock, incremented on every update
  createdBy:      ObjectId,
  createdAt:      Date, updatedAt: Date
}

// events collection — append-only, never updated or deleted
{
  organizationId:      ObjectId,
  campaignId:          ObjectId,
  campaignRecipientId: ObjectId,
  type: String,   // QUEUED|SENT|DELIVERED|OPENED|CLICKED|BOUNCED|COMPLAINED|FAILED|UNSUBSCRIBED — §8.2
  source: String, // worker|webhook|tracking-pixel|tracking-link|manual
  occurredAt: Date,
  meta: { ip: String, userAgent: String, url: String, bounceType: String },
  providerEventId: String // dedup key from the ESP, unique per (campaignRecipientId, type, providerEventId)
}

7.3 Rollups are derived, not hand-maintained

campaigns.stats is a cache. The events collection is the single source of truth; a rollup worker recomputes `stats` via an aggregation pipeline whenever a new event lands for that campaign, and the nightly reconciliation job in §29 re-derives all rollups from scratch to catch drift. This mirrors the reference plan's audit-history principle: never let a mutable summary field be the only record of what happened.

8. Campaign & Delivery State Machines

8.1 Campaign lifecycle (per campaign)

8.2 Per-recipient delivery pipeline (one state machine per campaign_recipients row)

Transitions only ever move forward or into a terminal side-state — no event handler ever downgrades a recipient from CLICKED back to SENT, even if webhook events arrive out of order (enforced by an explicit state-rank check in EventsService.applyEvent()).

9. Queues, Retries & Webhook Security

9.1 Retry & dead-letter handling

• Both queues use visibility timeout + exponential backoff; a message is retried up to 5 times before moving to its dedicated DLQ.
• A CloudWatch alarm fires when either DLQ depth > 0, paging the on-call channel (Slack webhook in the demo).
• DLQ messages can be replayed via an internal admin script that re-enqueues them onto the source queue after the root cause is fixed.

9.2 Webhook signature verification

// webhooks.controller.ts — simplified
@Post('ses')
async handleSesWebhook(@Req() req: RawBodyRequest<Request>) {
  const signature = req.headers['x-amz-sns-signature'];
  if (!this.snsVerifier.isValid(req.rawBody, signature)) {
    throw new UnauthorizedException('INVALID_WEBHOOK_SIGNATURE');
  }
  const payloadHash = sha256(req.rawBody);
  const alreadySeen = await this.webhookLogs.existsByHash(payloadHash);
  if (alreadySeen) return { accepted: true, duplicate: true }; // idempotent no-op
  await this.webhookLogs.record(payloadHash, req.rawBody);
  await this.sendQueue.enqueueWebhookEvent(req.body);
  return { accepted: true };
}

9.3 Duplicate-event protection

Two independent layers, matching how real ESPs actually misbehave: (1) the raw webhook payload is hashed and stored in webhook_logs before processing — an identical retry from the provider is dropped at the door; (2) inside processing, each derived events document has a unique compound index on (campaignRecipientId, type, providerEventId) — even a semantically-duplicate-but-differently-wrapped payload cannot double-count an open or a click.

10. Audit History & Logging

Every create/update/delete on campaigns, templates, contact_lists, and organization settings writes an audit_logs entry: { organizationId, userId, action, entityType, entityId, before, after, createdAt }. Combined with the immutable events collection (§7.3), the platform never has to guess what happened — only replay it. Application logs are structured JSON (pino), tagged with a request correlation id that is also attached to any SQS message the request produces, so a single campaign send can be traced end-to-end across the API process and the worker process in CloudWatch Logs Insights.

11. API Design Conventions

12. Response & Error Envelope

12.1 Success — single resource

{
  "success": true,
  "data": { "id": "66f1...", "name": "Spring Sale Launch", "status": "DRAFT" }
}

12.2 Success — paginated list

{
  "success": true,
  "data": [ /* array of resources */ ],
  "meta": { "page": 1, "limit": 20, "total": 143, "totalPages": 8 }
}

12.3 Error

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request payload failed validation.",
    "details": [ { "field": "subject", "message": "subject must be between 3 and 200 characters" } ]
  }
}

13. Error Code Catalog

14. API — Auth & Users

POST/api/v1/auth/register

Public Creates a new Organization and its first user (OWNER).

// Request
{ "organizationName": "NovaMail Retail Co.", "name": "Asha Rao", "email": "asha@novamail.demo", "password": "Str0ngPass!23" }

// 201 Response
{ "success": true, "data": { "user": { "id": "66f...", "role": "OWNER" }, "organization": { "id": "66f...", "name": "NovaMail Retail Co." }, "accessToken": "eyJ...", "refreshToken": "eyJ..." } }

POST/api/v1/auth/login

Public Authenticates a user and issues tokens.

POST/api/v1/auth/refresh

Public Exchanges a valid refresh token for a new access/refresh pair (rotation — the old refresh token is invalidated).

GET/api/v1/users/me

Any role Returns the caller's profile and organization summary.

GET/api/v1/users

ADMINOWNER Lists team members in the caller's organization (paginated, §24).

15. API — Campaigns & Templates

POST/api/v1/campaigns

MARKETER+ Creates a new campaign in DRAFT status.

GET/api/v1/campaigns

Paginated, filterable by status, searchable by name, sortable by createdAt|scheduledAt|name (§24).

GET/api/v1/campaigns/:id

Returns full campaign detail including current stats rollup. 404 CAMPAIGN_NOT_FOUND if absent or owned by another org.

PUT/api/v1/campaigns/:id

Edits a campaign. Allowed only while status = DRAFT; otherwise 400 INVALID_STATE_TRANSITION. Requires the client's last-seen version in the payload — mismatch returns 409 VERSION_CONFLICT (optimistic locking).

POST/api/v1/campaigns/:id/send-test

Sends the rendered campaign to up to 5 caller-supplied test addresses without creating campaign_recipients rows or affecting stats. Backed directly by the EmailProvider, bypassing the queue for immediate feedback.

POST/api/v1/campaigns/:id/schedule

POST/api/v1/campaigns/:id/cancel

Allowed from DRAFT, SCHEDULED, or PAUSED only. In-flight recipient sends already dispatched to SES are not recalled — only not-yet-dequeued jobs are dropped, and this distinction is shown to the user (§22.4).

GET/api/v1/campaigns/:id/recipients

Paginated per-recipient delivery status for one campaign — backs the recipient table in §22.4. Filterable by status.

Templates

16. API — Recipient Lists & Contacts

POST/api/v1/lists/:id/import

Imports contacts from a CSV previously uploaded to S3 via a presigned URL (frontend uploads directly to S3; this endpoint only registers the object key for async processing — see §22.6).

17. API — Sending & Webhook Ingestion

POST/api/v1/webhooks/ses

Public, signature-verified Receives SNS-wrapped SES delivery notifications (delivery, bounce, complaint). See §9.2 for the verification/dedup logic.

// Inbound SNS-wrapped SES bounce notification (abbreviated)
{
  "notificationType": "Bounce",
  "mail": { "messageId": "0102018f...", "destination": ["john@demo-inbox.test"] },
  "bounce": { "bounceType": "Permanent", "bounceSubType": "General" }
}

18. API — Public Tracking & Unsubscribe

GET/t/o/:token

Public 1×1 transparent GIF embedded in every sent email. A hit records an OPENED event.

GET/t/c/:token

Public Every link in an email body is rewritten to point here at send time; records a CLICKED event (also implies OPENED if not already recorded) and 302-redirects to the original destination URL stored alongside the token mapping.

POST/api/v1/unsubscribe/:token

Public Called by the one-click unsubscribe confirmation page (§22.9). Adds the recipient's email to suppressions (reason: unsubscribed) and records an UNSUBSCRIBED event. Idempotent — unsubscribing twice is a no-op success.

19. API — Analytics & Reporting

GET/api/v1/analytics/overview

Org-wide dashboard totals across a date range (default: last 30 days) — backs §22.2.

{ "success": true, "data": {
  "totalSent": 10000, "delivered": 9620, "opened": 5120, "clicked": 1240,
  "bounced": 280, "complained": 14, "failed": 100, "unsubscribed": 63,
  "deliveryRate": 96.2, "openRate": 53.2, "clickRate": 12.9, "bounceRate": 2.8
} }

GET/api/v1/analytics/campaigns/:id

Same shape, scoped to one campaign, plus a time-bucketed series (hourly for the first 48h) for the opens/clicks-over-time chart in §22.4.

20. Full Endpoint Index

21. Frontend Architecture

21.1 Data flow

21.2 State ownership rule

22. Screens & UI/UX Specification

Ten screens, each scoped to only the fields the corresponding business object actually needs (§2) — no vestigial "custom fields" builder, no multi-language editor, no drag-and-drop template designer (a plain HTML/merge-field editor is enough to prove the pipeline).

23. UI & Validation Standards

• Required fields are marked with a trailing * and enforced with the same Zod schema on the client as the DTO on the server — never a client rule looser or stricter than the API.
• Error messages are specific and actionable ("Subject must be 3–200 characters", not "Invalid input") and map 1:1 from the API's error.details[].message where present.
• Loading state: skeleton placeholders matching the real layout, never a bare spinner for content-shaped regions.
• Empty state: always distinguishes "nothing exists yet" (with a creation CTA) from "nothing matches your filter" (with a clear-filters action) — never the same message for both.
• Destructive/irreversible actions (delete, cancel a sending campaign, manual suppression) always show a confirm dialog naming the specific record and consequence.
• Toasts confirm every successful mutation ("Campaign scheduled for Aug 28, 9:00 AM"); errors surface inline near the offending field first, with a toast only as a secondary signal for whole-request failures.

24. Pagination, Filtering & Sorting

GET /api/v1/campaigns?page=1&limit=20&status=SENT&search=spring&sort=scheduledAt&direction=desc

Every list endpoint shares one PaginationQueryDto (page ≥ 1 default 1, limit 1-100 default 20, optional search, resource-specific status/filter fields, sort restricted to an allow-listed field set per resource, direction asc|desc) and one PaginatedResponse<T> shape (§12.2) so the frontend's shared DataTable component works identically across Campaigns, Templates, Lists, Contacts, and Suppressions.

25. Testing Strategy

26. Swagger / OpenAPI

Generated from NestJS decorators (@ApiTags, @ApiOperation, @ApiResponse, DTO @ApiProperty) and served at /api/docs in non-production environments. Every DTO documents its validation constraints inline so Swagger's "Try it out" reflects the same rules as §11–§19. The Swagger `info` block carries the branding fields described in §31.2.

27. Docker & Local Development

# infra/docker-compose.yml services
api        # NestJS HTTP server, port 3000
worker     # same image, different entrypoint (worker.ts) — consumes SQS
mongo      # MongoDB 7
mailhog    # local SMTP catcher — EmailProvider swaps to SmtpEmailProvider in dev, so no real email ever leaves a developer machine
localstack # emulates SQS + S3 + SNS locally, no AWS account needed for local dev

docker compose up brings up the full stack; npm run seed loads the fictional company "NovaMail Retail Co." with sample contacts, templates, and three campaigns in different lifecycle states for screenshots.

28. AWS Deployment Architecture

Deployment infra is documented (Terraform/CDK snippets under infra/aws/) but treated as optional for a reviewer — the Docker Compose stack in §27 is the primary "clone and run" path; AWS deployment is a secondary, fully-scripted path for anyone who wants to see it live.

29. Build Phases & Roadmap

30. Risks & Mitigations

31. Copyright, Trademark & Branding

Arsi India Info — Innovate · Integrate · Elevate.
Author of record for this repository and every file in it.

31.1 Two-layer licensing

Source code is released under the MIT License (permissive, encourages reuse for learning). The Arsi India Info name and logo are not part of that grant — they are covered by a separate TRADEMARK.md notice: forks and derivatives are welcome, but must not present themselves as Arsi India Info's own product or reuse its logo/branding.

31.2 Where the signature lives

31.3 Honest limits of watermarking a public repo

A watermark or footer string can always be stripped by someone who forks the code — it deters casual re-badging, it does not prevent a determined bad actor. Real proof of authorship for a portfolio comes from GitHub itself: commits under the Arsi India Info GitHub org, signed commits, a CODEOWNERS file, and SHA-256 checksums published against tagged releases. This plan treats visible branding as presentation, not enforcement.

32. Documentation Set & Portfolio Usage

33. Definition of Done

• All 29 endpoints in §20 implemented, validated, and covered by at least one integration test
• Every screen in §22 has loading, empty, error, and success states implemented — not just the happy path
• A full campaign lifecycle (create → schedule → send via Mailhog → webhook-simulated delivery/open/click/bounce → analytics reflect it) is demonstrable end-to-end with one seed script and no manual DB edits
• Tenant-isolation guardrail test (§6.1) and webhook idempotency test (§9.3) both pass in CI
• README, API docs, and the portfolio demo script (§32) are complete enough that someone who has never seen the repo can run it in under 10 minutes
• Branding present per the §31.2 table; LICENSE and TRADEMARK.md committed

© 2026 Arsi India Info. All rights reserved.

Email Campaign & Delivery Tracking Platform — source code licensed under MIT · name & logo protected under TRADEMARK.md
arsiindiainfo.com · github.com/arsiindiainfo