HN
HubNestv1.4.0
Get Started
Quickstart Guides

Go Quickstart

Complete end-to-end guide to send multi-channel notifications from a Go microservice — from API key generation to template creation, event triggering, and delivery verification.

1

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_...) — shown only once. Add it to your environment: export HUBNEST_API_KEY=hn_live_xxxxx.

Store rawKey immediately
The API key is hashed before storage and shown only once. Store it now in your environment or a secrets manager.
2

2. Create a Subscriber

Create a subscriber to represent a user in your system. Each subscriber has an externalId (your DB user ID), email, phone, and channel preferences.

setup/create_subscriber.sh
bash
1curl -X POST "https://api.hubnest.io/developer/subscribers" \
2 -H "Authorization: Bearer $HUBNEST_API_KEY" \
3 -H "Content-Type: application/json" \
4 -d '{
5 "externalId": "user_12345",
6 "email": "user@example.com",
7 "phone": "+919876543210",
8 "channelPrefs": { "email": true, "sms": true, "whatsapp": false, "push": false }
9 }'
10# Returns: { "id": "<subscriber-uuid>", "externalId": "user_12345", ... }
3

3. Create a Notification Template

Create a template that defines the notification content. Use {{variableName}} placeholders for dynamic content.

setup/create_template.sh
bash
1curl -X POST "https://api.hubnest.io/developer/templates" \
2 -H "Authorization: Bearer $HUBNEST_API_KEY" \
3 -H "Content-Type: application/json" \
4 -d '{
5 "type": "user.welcome",
6 "channel": "EMAIL",
7 "category": "TRANSACTIONAL",
8 "body": "Hi {{customerName}}, welcome to {{appName}}!",
9 "variablesSchema": ["customerName", "appName"]
10 }'
11# Returns: { "id": "<template-uuid>", "type": "user.welcome", ... }
4

4. Connect a Channel Provider

Go to Developer → Channels → Add Provider at https://app.hubnest.io. Use the built-in Demo Email for instant testing, or connect AWS SES, SendGrid, Twilio, MSG91, WhatsApp, FCM, or APNs for production.

5

5. Initialize Go Module

Create and initialize a new Go module:

terminal/go-init.sh
bash
1mkdir hubnest-go && cd hubnest-go
2go mod init hubnest-go
6

6. Trigger Event — Rules + Workflows Fire Automatically

POST to /api/v1/events using Go's net/http package — no external dependencies needed:

main.go
go
1package main
2
3import (
4 "bytes"
5 "encoding/json"
6 "fmt"
7 "io"
8 "net/http"
9 "os"
10)
11
12const baseURL = "https://api.hubnest.io"
13
14func triggerEvent(eventName, subscriberID, email string, payload map[string]string) {
15 body, _ := json.Marshal(map[string]interface{}{
16 "eventName": eventName,
17 "to": map[string]string{"subscriberId": subscriberID, "email": email},
18 "payload": payload,
19 })
20
21 req, _ := http.NewRequest("POST", baseURL+"/api/v1/events", bytes.NewBuffer(body))
22 req.Header.Set("Authorization", "Bearer "+os.Getenv("HUBNEST_API_KEY"))
23 req.Header.Set("Content-Type", "application/json")
24
25 client := &http.Client{}
26 resp, err := client.Do(req)
27 if err != nil {
28 panic(err)
29 }
30 defer resp.Body.Close()
31
32 respBody, _ := io.ReadAll(resp.Body)
33 fmt.Println("Status:", resp.Status)
34 fmt.Println("Response:", string(respBody))
35 // Response: {"status":"processed","eventName":"user.welcome","ruleMatched":false,"workflowsTriggeredCount":1}
36}
37
38func main() {
39 triggerEvent(
40 "user.welcome",
41 "<subscriber-uuid>",
42 "user@example.com",
43 map[string]string{"customerName": "Rahul Sharma", "appName": "Acme Inc"},
44 )
45}
7

7. Direct Send & Bulk Send

Direct send bypasses Rules/Workflows. Bulk campaign fans out to multiple recipients via Kafka:

direct_bulk.go
go
1// Direct individual send
2func sendDirect(recipient, templateID string) {
3 body, _ := json.Marshal(map[string]interface{}{
4 "recipient": recipient,
5 "channel": "EMAIL",
6 "templateId": templateID,
7 "category": "TRANSACTIONAL",
8 })
9 req, _ := http.NewRequest("POST", baseURL+"/api/v1/notifications/send", bytes.NewBuffer(body))
10 req.Header.Set("Authorization", "Bearer "+os.Getenv("HUBNEST_API_KEY"))
11 req.Header.Set("Content-Type", "application/json")
12 http.DefaultClient.Do(req)
13}
14
15// Bulk campaign
16func sendBulkCampaign(recipients []string, templateID string) {
17 body, _ := json.Marshal(map[string]interface{}{
18 "channel": "EMAIL",
19 "templateId": templateID,
20 "recipients": recipients,
21 "category": "MARKETING",
22 })
23 req, _ := http.NewRequest("POST", baseURL+"/api/campaigns", bytes.NewBuffer(body))
24 req.Header.Set("Authorization", "Bearer "+os.Getenv("HUBNEST_API_KEY"))
25 req.Header.Set("Content-Type", "application/json")
26 http.DefaultClient.Do(req)
27 // Response: { "message": "Fanned out N messages in campaign successfully via background queue.", "totalRecipients": "N" }
28}
8

8. Verify Delivery in Logs

Run your app with: go run main.go. Then go to Developer → Logs at https://app.hubnest.io to verify delivery status, latency, provider, and cost.

Environment variable setup
Run with: HUBNEST_API_KEY=hn_live_xxxxx go run main.go. Or set it in your system environment before running.

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?