> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aioka.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Subscribe to Newsletter

> Subscribe an email to the AIOKA newsletter — public, no API key required

## Overview

Public endpoint used by the newsletter signup form on `aioka.io`. Stores the
email in the `newsletter_subscribers` table, sends a welcome email via Resend,
and fires an admin Telegram notification.

**Tier:** Public ✅ — No API key required
**Rate limit:** 3 requests per IP per hour

## Spam Protection

* **Honeypot:** a hidden `website` field must be empty. Any non-empty value
  returns `400`.
* **Rate limit:** 3 attempts per IP per hour (Redis-backed sliding window).
* **Silent duplicate:** already-subscribed emails return `200` silently — no
  error, no resent welcome email. This prevents email enumeration and
  harvesting attacks.

## Request Fields

| Field     | Type   | Required | Description                        |
| --------- | ------ | -------- | ---------------------------------- |
| `email`   | string | ✅        | Valid email address, max 254 chars |
| `name`    | string | ❌        | Optional name, max 100 chars       |
| `website` | string | ❌        | Honeypot — must be empty           |

## Response Fields

| Field     | Type   | Description          |
| --------- | ------ | -------------------- |
| `message` | string | Confirmation message |

<RequestExample>
  ```bash curl theme={null}
  curl -X POST https://api.aioka.io/v1/newsletter/subscribe \
    -H "Content-Type: application/json" \
    -d '{"email": "user@example.com", "name": "Alice"}'
  ```

  ```python Python theme={null}
  import httpx

  resp = httpx.post(
      "https://api.aioka.io/v1/newsletter/subscribe",
      json={"email": "user@example.com", "name": "Alice"},
  )
  print(resp.json())
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "message": "Successfully subscribed to newsletter"
  }
  ```

  ```json 400 theme={null}
  {
    "detail": "Invalid email address"
  }
  ```

  ```json 429 theme={null}
  {
    "detail": "Too many requests. Please try again later."
  }
  ```
</ResponseExample>

## What Happens Next

1. Your email is stored in the `newsletter_subscribers` table.
2. A welcome email is sent to you via Resend with the subject
   *"Welcome to AIOKA — The Council Is Now Watching For You 👻"*.
3. The AIOKA owner is notified via Telegram.
4. You'll start receiving verdicts, council rulings, and market intelligence
   directly from the Judiciary Engine.

Visit [aioka.io/live](https://aioka.io/live) to watch the Council in real time.


## OpenAPI

````yaml POST /v1/newsletter/subscribe
openapi: 3.1.0
info:
  title: AIOKA Intelligence API
  description: |

    ## AI-powered crypto market intelligence

    AIOKA Intelligence API provides real-time access to our AI Council verdicts,
    market signals, regime detection, and Ghost Trader entry signals.

    ### Tiers
    - **Free**: 100 calls/day — Verdict + Regime
    - **Basic** ($49/mo): 1,000 calls/day — + Signals
    - **Pro** ($199/mo): 10,000 calls/day — + Council + Ghost

    ### Authentication
    Pass your API key in the `X-API-Key` header:

    ```
    X-API-Key: aik_free_xxxxxxxxxxxx
    ```

    ### Get your API key
    `POST /v1/keys/generate` (free tier, no credit card)
  contact:
    name: AIOKA Support
    url: https://docs.aioka.io/
    email: api@aioka.io
  license:
    name: Commercial
    url: https://aioka.io/terms
  version: 1.0.0
servers:
  - url: https://api.aioka.io
    description: Production — AIOKA Intelligence API
security: []
paths:
  /v1/newsletter/subscribe:
    post:
      tags:
        - Newsletter
      summary: Subscribe to the AIOKA newsletter
      description: >-
        Subscribe an email address to the AIOKA newsletter.


        **Auth:** None required — public endpoint.


        **Rate limit:** 3 requests per IP per hour.


        **Spam protection:** Honeypot `website` field must be empty.


        **Duplicate handling:** Already-subscribed emails return success
        silently

        (no error) to prevent email enumeration and harvesting.


        On new subscription, a welcome email is sent via Resend and the owner

        receives a Telegram notification.


        Returns 400 for invalid email, 429 if rate limit exceeded.
      operationId: subscribe_newsletter_v1_newsletter_subscribe_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NewsletterSubscribeRequest'
        required: true
      responses:
        '200':
          description: Successfully subscribed to newsletter
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NewsletterSubscribeResponse'
        '400':
          description: Invalid email address or honeypot triggered
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '429':
          description: Rate limit exceeded — max 3 per hour
      security: []
components:
  schemas:
    NewsletterSubscribeRequest:
      properties:
        email:
          type: string
          maxLength: 254
          title: Email
        name:
          anyOf:
            - type: string
              maxLength: 100
            - type: 'null'
          title: Name
        website:
          type: string
          maxLength: 500
          title: Website
          default: ''
      type: object
      required:
        - email
      title: NewsletterSubscribeRequest
    NewsletterSubscribeResponse:
      properties:
        message:
          type: string
          title: Message
      type: object
      required:
        - message
      title: NewsletterSubscribeResponse
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError

````