Quick Start¶

In this tutorial, you will create your first subscriber and assign tags -- in under 5 minutes.

Prerequisites¶

• Local Setup completed
• Server running on localhost:8000 (via make dev)
• Org-scoped API key available (see below)

1. Start the Development Environment¶

1
2
3
4
5

# Komplettes Setup (einmalig)
make setup

# Entwicklungsumgebung starten (Backend + Frontend + Celery Worker)
make dev

2. Create a Bootstrap API Key¶

After setup, create an org-scoped API key:

1

make api-key-bootstrap

1

export API_KEY="your-api-key-here"

3. Health Check¶

Verify that the API is reachable:

1

curl http://localhost:8000/health

Expected response:

1
2
3
4

{
  "status": "healthy",
  "version": "0.1.0"
}

4. Create a Tag¶

Create a tag for newsletter categories:

1
2
3
4
5
6
7
8
9

curl -X POST http://localhost:8000/api/v1/tags \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "product-updates",
    "display_name": "Product Updates",
    "description": "New features and improvements",
    "category": "newsletter"
  }'

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17

import os
import httpx

API_KEY = os.environ["API_KEY"]

client = httpx.Client(
    base_url="http://localhost:8000/api/v1",
    headers={"X-API-Key": API_KEY}
)

response = client.post("/tags", json={
    "name": "product-updates",
    "display_name": "Product Updates",
    "description": "New features and improvements",
    "category": "newsletter"
})
print(response.json())

5. Create a Subscriber¶

Register a new subscriber:

1
2
3
4
5
6
7
8
9

curl -X POST http://localhost:8000/api/v1/subscribers \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "first_name": "Max",
    "last_name": "Mustermann",
    "tags": ["product-updates"]
  }'

1
2
3
4
5
6
7
8
9

response = client.post("/subscribers", json={
    "email": "user@example.com",
    "first_name": "Max",
    "last_name": "Mustermann",
    "tags": ["product-updates"]
})
result = response.json()
subscriber = result["data"]
print(f"Subscriber ID: {subscriber['id']}")

6. Update Preferences¶

The subscriber wants to subscribe to an additional newsletter:

1
2
3
4
5
6
7

curl -X PATCH http://localhost:8000/api/v1/subscribers/{subscriber_id}/tags \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "add": ["weekly-digest"],
    "remove": []
  }'

1
2
3
4
5
6
7
8

response = client.patch(
    f"/subscribers/{subscriber['id']}/tags",
    json={
        "add": ["weekly-digest"],
        "remove": []
    }
)
print(response.json())

7. Query Preferences¶

View current subscriptions:

1
2

curl http://localhost:8000/api/v1/subscribers/{subscriber_id} \
  -H "X-API-Key: $API_KEY"

Response:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20

{
  "data": {
    "id": "uuid",
    "email": "user@example.com",
    "first_name": "Max",
    "last_name": "Mustermann",
    "status": "active",
    "tags": [
      {
        "name": "product-updates",
        "subscribed_at": "2024-01-15T10:30:00Z"
      },
      {
        "name": "weekly-digest",
        "subscribed_at": "2024-01-15T10:35:00Z"
      }
    ],
    "created_at": "2024-01-15T10:30:00Z"
  }
}

Summary¶

You have learned how to:

• Start the development environment with make dev
• Create an org-scoped bootstrap API key
• Perform an API health check
• Create tags for newsletter categories
• Register a subscriber with initial tags
• Update subscriber preferences
• Query current subscriptions

Next Steps¶