Email Campaign & Delivery Tracker — User Guide

1. Welcome

This platform is a fictional email marketing tool for NovaMail Retail Co. — build a contact list, write a template, send a campaign, and watch delivery events (sent, delivered, opened, clicked, bounced, complained, unsubscribed) roll in on the analytics page in real time. Every send in this demo goes through Mailhog/a sandboxed queue in non-production environments — no real email is ever sent to a real inbox outside of `production`.

2. Two Ways to Use This Platform

There's a real, working web application in front of this platform — you don't need to write any code or run any HTTP requests by hand to try it out.

3. Web App & API Reference

Everything is reachable from one public API base URL — there is exactly one entry point into the platform.

Response envelope

Every response — success or failure — is wrapped the same way, so client code only ever needs one shape to check:

// success
{
  "success": true,
  "data": { /* the actual result */ }
}

// list responses also include a "meta" block
{
  "success": true,
  "data": [ /* rows */ ],
  "meta": { "page": 1, "limit": 20, "total": 8 }
}

// failure
{
  "success": false,
  "error": { "code": "VALIDATION_ERROR", "message": "..." }
}

4. Demo Accounts & Roles

The seed script creates the fictional NovaMail Retail Co. organization with one account per role. Unlike a self-contained demo dataset, this platform is a real public multi-tenant SaaS — anyone can register their own organization (§7) — so the seeded accounts' credentials aren't published here; ask whoever manages this deployment for sign-in access, or register your own account to explore as an Owner immediately.

5. Which Screen Is For Which Role

Every signed-in user sees the same core navigation. An Analyst sees every screen below except the three write actions noted; a Owner who is also the platform admin additionally sees three screens under "Admin" in the sidebar.

6. Signing In

The sign-in page asks for your email, password, and a reCAPTCHA check.

Via the Web App

1. Open https://demo1.arsiindiainfo.com — you land on the sign-in page.
2. Enter your email and password.
3. Tick the reCAPTCHA checkbox — see the callout below.
4. Click Sign in. You land on the Dashboard (§9).

The sign-in page.

Via the API

POST https://demo1.arsiindiainfo.com/api/v1/auth/login
Content-Type: application/json

{
  "email": "you@example.com",
  "password": "...",
  "recaptchaToken": "03AGdBq27..."
}

{
  "success": true,
  "data": {
    "accessToken": "eyJhbGciOi...",
    "refreshToken": "9ba3b6cf3c...",
    "user": { "id": "...", "name": "...", "email": "...", "role": "OWNER", "organizationId": "..." },
    "organization": { "id": "...", "name": "NovaMail Retail Co.", "slug": "...", "senderVerified": true }
  }
}

Copy the accessToken and send it on every subsequent request as a bearer token:

Authorization: Bearer eyJhbGciOi...

7. Creating Your Own Organization

Unlike a fixed demo dataset, this platform is a genuine multi-tenant product — anyone can register, becoming the Owner of a brand-new, empty organization.

Via the Web App

1. Open the sign-in page and click Create an account.
2. Fill in your organization's name, your own name, email, and password, and complete the reCAPTCHA.
3. Submit — you're sent a verification email (Mailhog in non-production) rather than being signed in immediately.
4. Click the link in that email (or open /verify-email/:token directly) to activate the account, then sign in (§6).

Creating a new organization.

Via the API

POST/auth/register — { organizationName, name, email, password, recaptchaToken }. A duplicate email returns 409 DUPLICATE_NAME.

POST/auth/verify-email/:token — an invalid/expired token returns 400 INVALID_VERIFICATION_TOKEN.

8. Your Session & Signing Out

Access tokens are short-lived. The web app quietly exchanges the refreshToken for a new pair in the background whenever a request comes back 401 — you won't see a token expire while you're using the app.

POST/auth/refresh — { refreshToken }. POST/auth/logout revokes the refresh token so it can no longer be used.

Via the Web App: click Sign out in the sidebar. Via the API: GET/users/me returns your own profile.

9. The Dashboard

The Dashboard is the landing page after sign-in — a KPI row and your organization's most recent campaigns.

Via the Web App: KPI cards (total sent, delivery rate, open rate, click rate) and a recent-campaigns table with each one's status pill.

The Dashboard — signed in as Owner for NovaMail Retail Co.

Via the API: GET/analytics/overview returns the same numbers scoped to your organization.

10. Contact Lists & Importing

A campaign always sends to exactly one list. Lists hold contacts; a contact can belong to more than one list.

Via the Web App

1. Open Lists — click + New List to create one, or click any row to open its detail page.
2. On a list's detail page, add a contact one at a time, or click Import CSV to bulk-upload (name/email columns).
3. A contact who bounced or complained on any send shows an auto-suppressed badge — see §15, it's platform-wide, not per-list.

Recipient lists.

A list's detail page — note the auto-suppressed contact.

Creating a new list.

Via the API

POST/lists — { name }. POST/lists/:id/contacts — add one contact directly.

Bulk import is a three-step, presigned-upload flow (§20 covers the same pattern for webhooks):

1. POST/lists/:id/imports/presign — get a short-lived upload URL for your CSV.
2. Upload the file straight to that URL (never through this API).
3. POST/lists/:id/import — kick off processing; poll GET/lists/:id/imports/:jobId for progress.

11. Templates & the Editor

A template is the reusable email body a campaign sends — subject line, HTML body, and merge fields like {{firstName}}.

Via the Web App

1. Open Templates — click + New Template or click any row to edit.
2. The editor has merge-field shortcut buttons and a live preview pane rendered with sample contact data.
3. Every template needs at least one unsubscribe merge tag before it can be used in a send — the editor warns you if it's missing.

The Templates list.

The template editor — merge fields on the left, live preview on the right.

Via the API

POST/templates · GET/templates · PUT/templates/:id · DELETE/templates/:id. A missing/unresolvable template on a campaign returns 404 TEMPLATE_NOT_FOUND.

12. Creating a Campaign

The campaign wizard ties a list and a template together, with your organization's verified sender applied automatically.

Via the Web App

1. Open Campaigns and click + New Campaign.
2. Name the campaign, pick a list and a template — your org's sender domain (§16) is applied without asking.
3. Save — the campaign starts in Draft. It isn't sent until §13.

Step 1 — Details. The From email must use your verified sender domain (§16).

Step 2 — Recipients. Pick one or more lists; the wizard totals the recipient count.

Step 3 — Content. Pick a template; the preview renders it with sample data.

Step 4 — Review & Schedule (§13) — Send now, or pick a future time.

Exactly that — a second tab's stale save gets caught, not silently applied.

Via the API

POST/campaigns — { name, listId, templateId }. PUT/campaigns/:id — { ..., version }; a stale version returns 409 VERSION_CONFLICT.

13. Sending — the Delivery Pipeline

A campaign moves through six states; a per-recipient row inside it moves through its own, longer pipeline.

Campaign lifecycle

Via the Web App

1. Open a Draft campaign and click Schedule — pick a future time, or choose Send now for an immediate queue.
2. While Sending, click Pause/Resume to hold or continue dispatch, or Cancel to stop it for good.
3. The campaign flips to Sent once every recipient has been dispatched.

Per-recipient delivery pipeline

Watching it happen: the analytics page (§14) polls every 15 seconds while a campaign is Sending, so the funnel and per-recipient table update live as delivery events arrive.

Via the API

POST/campaigns/:id/schedule — { sendAt? }; omit sendAt (or set it to now) for an immediate send. POST/campaigns/:id/pause · POST/campaigns/:id/resume · POST/campaigns/:id/cancel. POST/campaigns/:id/send-test — { emails: string[] }, up to 5 addresses, doesn't touch the real recipient list. GET/campaigns/:id/recipients — every recipient's current status.

14. Campaign Analytics

Every number here is derived from the append-only event log described in §13 — nothing is a running counter that could drift.

Via the Web App: open a campaign to see its funnel (Queued → Sent → Delivered → Opened → Clicked, with Bounced/Complained side-counts), an opens/clicks time-series chart, and the per-recipient status table.

Via the API: GET/analytics/campaigns/:id returns the funnel counts and time series as one payload.

15. Suppressions

An address on the suppression list will never receive another send from this organization — added automatically on a bounce/complaint/unsubscribe, or manually.

Suppressions — populated rows show why each address landed here (bounce, complaint, unsubscribe, or manual).

Adding one manually.

Via the API: GET/suppressions · POST/suppressions — add one manually. DELETE/suppressions/:id — remove one (use sparingly; it doesn't undo why they were suppressed).

A campaign send silently skips any recipient already on this list — no error, they're just not queued, so re-sending to a list with suppressed contacts is always safe.

16. Settings & Sender Domain

A campaign can't be scheduled until your organization's sender domain is verified. Settings has three tabs: Organization (sender domain/email), Team (your org's own members, distinct from the platform-wide Admin: Users in §17), and API / Webhooks (§20).

Via the Web App: open Settings (Admin role or above) to see your sender domain/email and its verification status; click Save to update it.

Settings — Organization tab, sender domain verification.

Settings — Team tab, this organization's own members (§4's roles).

Via the API: GET/organizations/me · PUT/organizations/me · POST/organizations/me/verify-sender. Scheduling a campaign for an unverified sender returns 422 SENDER_NOT_VERIFIED.

17. Admin: Users

Sign in as the platform admin (§4) to see every user across every organization on the platform — not just your own. These endpoints return 403 FORBIDDEN_ROLE for anyone else.

Admin: Users — cross-organization, deliberately bypassing the usual org-scoped view.

Via the API: GET/admin/users · PATCH/admin/users/:id/block · PATCH/admin/users/:id/unblock · DELETE/admin/users/:id. A blocked/deleted platform admin account is refused outright, so the platform can never end up with zero admins.

18. Admin: Contacts

Because anyone can register and import a contact list, every imported contact starts Pending until a platform admin approves or rejects it — the abuse guardrail mentioned in §4.

Via the Web App: filter by Pending/Approved/Rejected, and click Approve or Reject on any row.

Admin: Contacts — the moderation queue for imported recipients.

Via the API: GET/admin/contacts?status= · PATCH/admin/contacts/:id/approve · PATCH/admin/contacts/:id/reject. A campaign only ever sends to Approved contacts.

19. Admin: Send Log

Every demo send, across every organization, in one place — how a platform admin watches for abuse of the shared send quota (§4).

Admin: Send Log.

Via the API: GET/admin/send-log.

20. Webhooks & Public Tracking

Delivery events arrive two ways, both outside the normal bearer-token API:

Settings → API / Webhooks — the URL to configure as your SES/SNS delivery-notification destination.

• Inbound webhook — POST/webhooks/ses receives an SES/SNS-shaped payload for delivered/bounced/complained. It's HMAC-signed; an invalid signature returns 401 INVALID_WEBHOOK_SIGNATURE before anything is processed. Duplicate delivery of the same event is a no-op, not a double-count — every event carries an id the consumer de-dupes on.
• Client-side tracking — the tracking pixel (GET /t/o/:token) records an OPENED event; the click redirect (GET /t/c/:token) records CLICKED (implying OPENED too) before 302-ing to the real destination. Both are unversioned since they're embedded in already-sent emails that can't be updated after the fact.

Unsubscribe: GET/unsubscribe/:token is public and idempotent — clicking it twice is a no-op success the second time, never an error.

21. Error Responses

22. Full Endpoint Reference

All paths (except the public tracking/unsubscribe/webhook routes noted) are relative to https://demo1.arsiindiainfo.com/api/v1.

23. FAQ & Troubleshooting

The reCAPTCHA checkbox won't check, or my login/registration is rejected

Make sure third-party content isn't blocked by a privacy extension — the widget loads a script from google.com. If the checkbox works but submission still fails, the token likely expired (valid for about two minutes) — the form resets the widget automatically; complete it again and resubmit.

I registered but never got a verification email

In non-production environments, verification emails go to Mailhog, not a real inbox — ask whoever manages this deployment where to view it. The account is genuinely unusable (§7) until that link is clicked.

I sent a campaign but the recipient count is lower than my list's contact count

Two reasons this is expected: suppressed addresses (§15) are silently skipped, and imported contacts that haven't been approved yet by a platform admin (§18) never receive a send.

Why can't I resume a Cancelled campaign?

Cancelled is terminal by design (§13) — Paused is the only "stopped but resumable" state. Create a new campaign instead.

Can I make myself a platform admin?

No — isPlatformAdmin is set only via seed/ops, never through any endpoint or UI action, by design.

Where do I see the full request/response schema for every field?

The interactive Swagger UI at /api/docs documents every field, validation rule, and example — it's disabled on the public demo (ENVIRONMENT === 'production' turns it off), so run the project locally (see the repo's README) to browse it.

Need more detail? This guide covers the day-to-day workflows. Schema, event sourcing, and API contract details are documented separately in the project's docs/ folder (data model, deployment, testing).

© 2026 Arsi India Info. All rights reserved.

Email Campaign & Delivery Tracker — a portfolio build modeled on NovaMail Retail Co.
Source code licensed under MIT · name & logo protected under TRADEMARK.md
arsiindiainfo.com