Custom Newsletter Website

Visitor browser -> your website/backend -> Maito API

Build a custom newsletter website for Maito.

Maito is the newsletter backend and source of truth. The website must show public newsletter issues, issue detail pages, categories, and a subscribe form.

Security requirements:
- Never expose the Maito API key in browser code.
- Store the API key as a server-side environment variable named MAITO_API_KEY.
- All browser requests must go to local backend routes in this project.
- Local backend routes must call the Maito API with:
  Authorization: Bearer process.env.MAITO_API_KEY
- The Maito API base URL is:
  https://api.getmaito.com/v1

Build these pages:

1. Newsletter homepage / archive
   - Fetch public sent issues from the server.
   - Use:
     GET https://api.getmaito.com/v1/newsletter/issues?status=sent&isPublic=true&limit=50
   - Render issue title, preview text, thumbnail if available, category if available, and link to the issue slug page.
   - Documentation:
     /api-reference/newsletter/list-issues

2. Issue detail page
   - Use a dynamic slug route.
   - Fetch one public issue by slug from the server.
   - Use:
     GET https://api.getmaito.com/v1/newsletter/issues/by-slug/{issueSlug}
   - Render subject, preview text, contentHtml, category, and sent date if available.
   - Documentation:
     /api-reference/newsletter/get-issue-by-slug

3. Categories
   - Fetch newsletter categories from the server.
   - Use:
     GET https://api.getmaito.com/v1/newsletter/categories
   - Render category navigation.
   - If building category archive pages, fetch public issues and filter by issue.category.slug or issue.categories.
   - Documentation:
     /api-reference/newsletter/list-categories

4. Subscribe form
   - The frontend form should submit only to a local backend route, for example /api/subscribe.
   - The local backend route should validate the email and then call Maito.
   - Use:
     POST https://api.getmaito.com/v1/newsletter/subscribers
     - Body example:
     {
       "email": "reader@example.com",
       "sourceType": "api",
       "source": "custom_website",
       "optInAttestation": true
     }
   - optInAttestation must be true only when the visitor explicitly submits the subscribe form.
   - Documentation:
     /api-reference/newsletter/create-subscriber

Recommended implementation if using Next.js App Router:
- Use server components or route handlers for Maito reads.
- Create app/page.tsx for the newsletter archive.
- Create app/issues/[slug]/page.tsx for issue pages.
- Create app/categories/[slug]/page.tsx only if category pages are needed.
- Create app/api/subscribe/route.ts for the subscribe form.
- Put MAITO_API_KEY in .env.local and never prefix it with NEXT_PUBLIC_.
- Return only the fields the frontend needs from local API routes.
- Show user-friendly subscribe success and error states.

Maito API responses use this shape:
{
  "ok": true,
  "data": {}
}

Error responses use this shape:
{
  "ok": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request."
  }
}

Use these docs while building:
- API authentication: /api-reference/authentication
- API responses and errors: /api-reference/responses
- List issues: /api-reference/newsletter/list-issues
- Get issue by slug: /api-reference/newsletter/get-issue-by-slug
- List categories: /api-reference/newsletter/list-categories
- Create subscriber: /api-reference/newsletter/create-subscriber