Quickstart Guides

Python Quickstart

Complete end-to-end guide to send multi-channel notifications from a Python application (Django, Flask, FastAPI, or plain script) — from API key generation to template creation, event triggering, and delivery verification.

1. Sign Up & Get API Key

Register at https://app.hubnest.io. Go to Developer → API Keys → Generate New Key. Copy the rawKey (hn_live_...) immediately — it is shown only once. Store it in your environment variables.

Store rawKey immediately

Add HUBNEST_API_KEY=hn_live_xxxxx to your .env file or system environment. The rawKey is hashed before storage and shown only once.

2. Create a Subscriber

Subscribers represent your app users. Create one to map email/phone to a subscriberId for targeted delivery.

setup/create_subscriber.py

python

1import requests, os

3HUBNEST_API_KEY = os.environ['HUBNEST_API_KEY']

4BASE_URL = 'https://api.hubnest.io'

5HEADERS = {'Authorization': f'Bearer {HUBNEST_API_KEY}', 'Content-Type': 'application/json'}

7# Create a subscriber

8res = requests.post(f'{BASE_URL}/developer/subscribers', headers=HEADERS, json={

9 'externalId': 'user_12345',

10 'email': 'user@example.com',

11 'phone': '+919876543210',

12 'channelPrefs': {'email': True, 'sms': True, 'whatsapp': True, 'push': False}

13})

14subscriber = res.json()

15print('Subscriber created:', subscriber['id'])

16# Save subscriber['id'] as SUBSCRIBER_ID — use as subscriberId in event triggers

3. Create a Notification Template

Create templates with {{variable}} placeholders. Variables are auto-extracted from the body if variablesSchema is omitted.

setup/create_template.py

python

1# Create a notification template

2res = requests.post(f'{BASE_URL}/developer/templates', headers=HEADERS, json={

3 'type': 'user.welcome',

4 'channel': 'EMAIL',

5 'category': 'TRANSACTIONAL',

6 'body': 'Hi {{customerName}}, welcome to {{appName}}! Your account is ready.',

7 'variablesSchema': ['customerName', 'appName']

8})

9template = res.json()

10print('Template created:', template['id'])

11# template['id'] (UUID) = templateId used in /api/v1/notifications/send

12# template['type'] = 'user.welcome' — used in Workflow SEND_ACTION nodes

4. Connect a Channel Provider

Go to Developer → Channels → Add Provider at https://app.hubnest.io. Use Demo Email for instant testing, or connect AWS SES, SendGrid, Twilio, MSG91, WhatsApp, FCM, or APNs for production. See channel-specific docs for credential formats.

5. Install requests Library

Install the HTTP library:

terminal/install.sh

bash

1pip install requests

3# Or with python-dotenv for .env file support:

4pip install requests python-dotenv

6. Trigger Event — Rules + Workflows Fire Automatically

POST to /api/v1/events — HubNest evaluates all active Rules and Workflows and dispatches matching notifications:

send_notification.py

python

1import requests, os

3HUBNEST_API_KEY = os.environ['HUBNEST_API_KEY']

4BASE_URL = 'https://api.hubnest.io'

5HEADERS = {'Authorization': f'Bearer {HUBNEST_API_KEY}', 'Content-Type': 'application/json'}

7def trigger_event(event_name, subscriber_id, email, payload):

8 res = requests.post(

9 f'{BASE_URL}/api/v1/events',

10 headers=HEADERS,

11 json={

12 'eventName': event_name,

13 'to': {'subscriberId': subscriber_id, 'email': email},

14 'payload': payload

15 }

16 )

17 res.raise_for_status()

18 return res.json()

20# Usage — triggers Rules + Workflows

21result = trigger_event(

22 'user.welcome',

23 '<subscriber-uuid>',

24 'user@example.com',

25 {'customerName': 'Rahul Sharma', 'appName': 'Acme Inc'}

26)

27print('Workflows triggered:', result['workflowsTriggeredCount'])

28print('Rule matched:', result['ruleMatched'])

7. Direct Send & Bulk Send

Direct send bypasses Rules/Workflows. Bulk campaign fans out to a list via Kafka queue:

send_direct_and_bulk.py

python

1# Direct individual send (bypasses Rules & Workflow engine)

2def send_direct(recipient, template_id, variables):

3 res = requests.post(

4 f'{BASE_URL}/api/v1/notifications/send',

5 headers=HEADERS,

6 json={'recipient': recipient, 'channel': 'EMAIL', 'templateId': template_id, 'variables': variables, 'category': 'TRANSACTIONAL'}

7 )

8 return res.json() # { 'notificationId': ..., 'status': ... }

10# Bulk campaign

11def send_bulk(recipients, template_id):

12 res = requests.post(

13 f'{BASE_URL}/api/campaigns',

14 headers=HEADERS,

15 json={'channel': 'EMAIL', 'templateId': template_id, 'recipients': recipients, 'category': 'MARKETING'}

16 )

17 return res.json() # { 'message': 'Fanned out N messages...', 'totalRecipients': 'N' }

8. Verify Delivery in Logs

Run your script with python send_notification.py, then go to Developer → Logs at https://app.hubnest.io to see delivery status, latency, provider used, and wallet cost for each notification dispatched.

Configure a webhook for real-time callbacks

Set up a Webhook at Developer → Webhooks to receive DELIVERED/FAILED callbacks at your own endpoint in real time.

Next steps

AWS SES Email

Configure AWS SES IAM keys, verified domains, and sending rate limits.

SendGrid Email

Connect SendGrid API Keys and verified sender identities.

Twilio SMS Provider

Connect Twilio Account SID, Auth Token, and phone numbers.

WhatsApp Business

Connect Meta WhatsApp Cloud API access tokens and phone number IDs.

Was this guide helpful?