Guides
Get API KeyHome

Go

Send SMS or MMS with the CloudContactAI Go SDK

🔑

Get API Key

Learn how to send your first SMS or MMS using the CCAI Go SDK

Prerequisites

To get the most out of this guide, you'll need to:

  • Sign up for a CCAI Trial Account here
  • Get your Client ID from Account\Settings
  • Create\Copy an API Key from Account Settings

1. Install

Get the CCAI Go SDK.

go get github.com/cloudcontactai/ccai-go

2. Send SMS message

package main

import (
	"fmt"
	"log"

	"github.com/cloudcontactai/ccai-go/pkg/ccai"
	"github.com/cloudcontactai/ccai-go/pkg/sms"
)

func main() {
	// Initialize the client
	client, err := ccai.NewClient(ccai.Config{
		ClientID: "YOUR-CLIENT-ID",
		APIKey:   "YOUR-API-KEY",
	})
	if err != nil {
		log.Fatalf("Failed to create CCAI client: %v", err)
	}

	// Send a single SMS
	response, err := client.SMS.SendSingle(
		"John",
		"Doe",
		"+15551234567",
		"Hello ${firstName}, this is a test message!",
		"Test Campaign",
		nil,
	)
	if err != nil {
		log.Fatalf("Failed to send SMS: %v", err)
	}

	fmt.Printf("Message sent with ID: %s\n", response.ID)

	// Send to multiple recipients
	accounts := []sms.Account{
		{
			FirstName: "John",
			LastName:  "Doe",
			Phone:     "+15551234567",
		},
		{
			FirstName: "Jane",
			LastName:  "Smith",
			Phone:     "+15559876543",
		},
	}

	campaignResponse, err := client.SMS.Send(
		accounts,
		"Hello ${firstName} ${lastName}, this is a test message!",
		"Bulk Test Campaign",
		nil,
	)
	if err != nil {
		log.Fatalf("Failed to send bulk SMS: %v", err)
	}

	fmt.Printf("Campaign sent with ID: %s\n", campaignResponse.CampaignID)
}

3. Send MMS message

package main

import (
	"fmt"
	"log"

	"github.com/cloudcontactai/ccai-go/pkg/ccai"
	"github.com/cloudcontactai/ccai-go/pkg/sms"
)

func main() {
	// Initialize the client
	client, err := ccai.NewClient(ccai.Config{
		ClientID: "YOUR-CLIENT-ID",
		APIKey:   "YOUR-API-KEY",
	})
	if err != nil {
		log.Fatalf("Failed to create CCAI client: %v", err)
	}

	// Define progress tracking
	options := &sms.Options{
		Timeout: 60,
		OnProgress: func(status string) {
			fmt.Printf("Progress: %s\n", status)
		},
	}

	// Complete MMS workflow (get URL, upload image, send MMS)
	imagePath := "path/to/your/image.jpg"
	contentType := "image/jpeg"

	// Define recipient
	account := sms.Account{
		FirstName: "John",
		LastName:  "Doe",
		Phone:     "+15551234567",  // Use E.164 format
	}

	// Send MMS with image in one step
	response, err := client.MMS.SendWithImage(
		imagePath,
		contentType,
		[]sms.Account{account},
		"Hello ${firstName}, check out this image!",
		"MMS Campaign Example",
		options,
		true,
	)
	if err != nil {
		log.Fatalf("Error sending MMS: %v", err)
	}

	fmt.Printf("MMS sent! Campaign ID: %s\n", response.CampaignID)
}

4. Send MMS with Environment Variables

package main

import (
    "fmt"
    "log"
    "os"

    "github.com/cloudcontactai/ccai-go/pkg/ccai"
    "github.com/cloudcontactai/ccai-go/pkg/sms"
    "github.com/joho/godotenv"
)

func main() {
    // Load environment variables
    err := godotenv.Load()
    if err != nil {
        log.Printf("Warning: Could not load .env file: %v", err)
    }

    // Initialize the client
    client, err := ccai.NewClient(ccai.Config{
        ClientID: os.Getenv("CCAI_CLIENT_ID"),
        APIKey:   os.Getenv("CCAI_API_KEY"),
    })
    if err != nil {
        log.Fatalf("Failed to create CCAI client: %v", err)
    }

	// Define progress tracking
	options := &sms.Options{
		Timeout: 60,
		OnProgress: func(status string) {
			fmt.Printf("Progress: %s\n", status)
		},
	}

	// Complete MMS workflow (get URL, upload image, send MMS)
	imagePath := "path/to/your/image.jpg"
	contentType := "image/jpeg"

	// Define recipient
	account := sms.Account{
		FirstName: "John",
		LastName:  "Doe",
		Phone:     "+14156566694",  // Use E.164 format
	}

	// Send MMS with image in one step
	response, err := client.MMS.SendWithImage(
		imagePath,
		contentType,
		[]sms.Account{account},
		"Hello ${firstName}, check out this image!",
		"MMS Campaign Example",
		options,
		true,
	)
	if err != nil {
		log.Fatalf("Error sending MMS: %v", err)
	}

	fmt.Printf("MMS sent! Campaign ID: %s\n", response.CampaignID)
}

5. Step-by-Step MMS Workflow

// Step 1: Get a signed URL for uploading
uploadResponse, err := client.MMS.GetSignedUploadURL(
	"image.jpg",
	"image/jpeg",
	"",
	true,
)
if err != nil {
	log.Fatalf("Error getting signed URL: %v", err)
}

signedURL := uploadResponse.SignedS3URL
fileKey := uploadResponse.FileKey

// Step 2: Upload the image to the signed URL
uploadSuccess, err := client.MMS.UploadImageToSignedURL(
	signedURL,
	"path/to/your/image.jpg",
	"image/jpeg",
)
if err != nil {
	log.Fatalf("Error uploading image: %v", err)
}

if uploadSuccess {
	// Step 3: Send the MMS with the uploaded image
	response, err := client.MMS.Send(
		fileKey,
		accounts,
		"Hello ${firstName}, check out this image!",
		"MMS Campaign Example",
		nil,
		true,
	)
	if err != nil {
		log.Fatalf("Error sending MMS: %v", err)
	}

	fmt.Printf("MMS sent! Campaign ID: %s\n", response.CampaignID)
}

6. With Progress Tracking

// Create options with progress tracking
options := &sms.Options{
	Timeout: 60,
	Retries: 3,
	OnProgress: func(status string) {
		fmt.Printf("%s - %s\n", time.Now().Format("2006-01-02 15:04:05"), status)
	},
}

// Send SMS with progress tracking
response, err := client.SMS.Send(
	accounts,
	message,
	title,
	options,
)

7. Send Email

package main

import (
	"fmt"
	"log"
	"os"

	"github.com/cloudcontactai/ccai-go/pkg/ccai"
	"github.com/cloudcontactai/ccai-go/pkg/email"
	"github.com/joho/godotenv"
)

func main() {
	_ = godotenv.Load()

	client, err := ccai.NewClient(ccai.Config{
		ClientID: os.Getenv("CCAI_CLIENT_ID"),
		APIKey:   os.Getenv("CCAI_API_KEY"),
	})
	if err != nil {
		log.Fatalf("Failed to create client: %v", err)
	}

	// Send a single email
	response, err := client.Email.SendSingle(
		"John",
		"Doe",
		"[email protected]",
		"Welcome to Our Service",
		"<p>Hello John,</p><p>Thank you for signing up!</p>",
		"[email protected]",
		"[email protected]",
		"Your Company",
		"Welcome Email",
	)
	if err != nil {
		log.Fatalf("Failed to send email: %v", err)
	}

	fmt.Printf("Email sent with ID: %s\n", response.ID)

	// Send email campaign
	emailAccounts := []email.Account{
		{FirstName: "John", LastName: "Doe", Email: "[email protected]"},
		{FirstName: "Jane", LastName: "Smith", Email: "[email protected]"},
	}

	campaignResponse, err := client.Email.Send(
		emailAccounts,
		"Monthly Newsletter",
		"<h1>Newsletter</h1><p>Hello ${firstName}, here are our updates...</p>",
		"[email protected]",
		"[email protected]",
		"Your Company Newsletter",
		"July Newsletter",
		nil,
	)
	if err != nil {
		log.Fatalf("Failed to send email campaign: %v", err)
	}

	fmt.Printf("Email campaign sent with ID: %s\n", campaignResponse.CampaignID)
}

8. Webhooks

package main

import (
	"fmt"
	"log"
	"os"

	"github.com/cloudcontactai/ccai-go/pkg/ccai"
	"github.com/joho/godotenv"
)

func main() {
	_ = godotenv.Load()

	client, err := ccai.NewClient(ccai.Config{
		ClientID: os.Getenv("CCAI_CLIENT_ID"),
		APIKey:   os.Getenv("CCAI_API_KEY"),
	})
	if err != nil {
		log.Fatalf("Failed to create client: %v", err)
	}

	// Register a webhook
	webhook, err := client.Webhook.Register("https://your-app.com/webhook", "POST", "ALL")
	if err != nil {
		log.Fatalf("Failed to register webhook: %v", err)
	}
	fmt.Printf("Webhook registered with ID: %s\n", webhook.ID)
	fmt.Printf("Secret Key: %s\n", webhook.SecretKey)

	// List webhooks
	webhooks, err := client.Webhook.List()
	if err != nil {
		log.Fatalf("Failed to list webhooks: %v", err)
	}
	for _, wh := range webhooks {
		fmt.Printf("Webhook ID: %s, URL: %s\n", wh.ID, wh.URL)
	}

	// Delete a webhook
	err = client.Webhook.Delete(webhook.ID)
	if err != nil {
		log.Fatalf("Failed to delete webhook: %v", err)
	}
	fmt.Println("Webhook deleted successfully")
}

9. Contact Validator

Validate email addresses and phone numbers.

Bulk endpoints accept up to 50 contacts per request and are processed server-side in chunks.

package main

import (
	"fmt"
	"log"
	"os"

	"github.com/cloudcontactai/ccai-go/src/pkg/ccai"
	"github.com/cloudcontactai/ccai-go/src/pkg/contactvalidator"
	"github.com/joho/godotenv"
)

func main() {
	_ = godotenv.Load()

	client, err := ccai.NewClient(ccai.Config{
		ClientID: os.Getenv("CCAI_CLIENT_ID"),
		APIKey:   os.Getenv("CCAI_API_KEY"),
	})
	if err != nil {
		log.Fatalf("Failed to create client: %v", err)
	}

	// Validate a single email
	emailResult, err := client.ContactValidator.ValidateEmail("[email protected]")
	if err != nil {
		log.Fatalf("Failed to validate email: %v", err)
	}
	fmt.Printf("Email status: %s\n", emailResult.Status) // "valid" | "invalid" | "risky"

	// Validate multiple emails (up to 50)
	bulkEmails, err := client.ContactValidator.ValidateEmails([]string{
		"[email protected]",
		"[email protected]",
	})
	if err != nil {
		log.Fatalf("Failed to validate emails: %v", err)
	}
	fmt.Printf("Email summary: %+v\n", bulkEmails.Summary)

	// Validate a single phone number
	phoneResult, err := client.ContactValidator.ValidatePhone("+15551234567", "US")
	if err != nil {
		log.Fatalf("Failed to validate phone: %v", err)
	}
	fmt.Printf("Phone status: %s\n", phoneResult.Status) // "valid" | "invalid" | "landline"

	// Validate multiple phone numbers (up to 50)
	bulkPhones, err := client.ContactValidator.ValidatePhones([]contactvalidator.PhoneInput{
		{Phone: "+15551234567"},
		{Phone: "+15559876543", CountryCode: "US"},
	})
	if err != nil {
		log.Fatalf("Failed to validate phones: %v", err)
	}
	fmt.Printf("Phone summary: %+v\n", bulkPhones.Summary)
}

10. Brand Registration

Register and manage brands for TCR verification.

package main

import (
	"fmt"
	"log"
	"os"

	"github.com/cloudcontactai/ccai-go/src/pkg/brands"
	"github.com/cloudcontactai/ccai-go/src/pkg/ccai"
	"github.com/joho/godotenv"
)

func strPtr(s string) *string { return &s }

func main() {
	_ = godotenv.Load()

	client, err := ccai.NewClient(ccai.Config{
		ClientID: os.Getenv("CCAI_CLIENT_ID"),
		APIKey:   os.Getenv("CCAI_API_KEY"),
	})
	if err != nil {
		log.Fatalf("Failed to create client: %v", err)
	}

	// Create a brand
	brand, err := client.Brands.Create(brands.BrandRequest{
		LegalCompanyName: strPtr("Collect.org Inc."),
		Dba:              strPtr("Collect"),
		EntityType:       strPtr("NON_PROFIT"),
		TaxId:            strPtr("123456789"),
		TaxIdCountry:     strPtr("US"),
		Country:          strPtr("US"),
		VerticalType:     strPtr("NON_PROFIT"),
		WebsiteUrl:       strPtr("https://www.collect.org"),
		Street:           strPtr("123 Main Street"),
		City:             strPtr("San Francisco"),
		State:            strPtr("CA"),
		PostalCode:       strPtr("94105"),
		ContactFirstName: strPtr("Jane"),
		ContactLastName:  strPtr("Doe"),
		ContactEmail:     strPtr("[email protected]"),
		ContactPhone:     strPtr("+14155551234"),
	})
	if err != nil {
		log.Fatalf("Failed to create brand: %v", err)
	}
	fmt.Printf("Brand created with ID: %d\n", brand.ID)

	// Get a brand by ID
	fetched, _ := client.Brands.Get(brand.ID)
	fmt.Printf("Brand name: %s\n", fetched.LegalCompanyName)

	// List all brands
	brandList, _ := client.Brands.List()
	fmt.Printf("Total brands: %d\n", len(brandList))

	// Update a brand (partial update)
	client.Brands.Update(brand.ID, brands.BrandRequest{
		Street: strPtr("456 Oak Avenue"),
		City:   strPtr("Los Angeles"),
	})

	// Delete a brand
	client.Brands.Delete(brand.ID)
}

Entity Types: PRIVATE_PROFIT, PUBLIC_PROFIT, NON_PROFIT, GOVERNMENT, SOLE_PROPRIETOR

Vertical Types: AUTOMOTIVE, AGRICULTURE, BANKING, COMMUNICATION, CONSTRUCTION, EDUCATION, ENERGY, ENTERTAINMENT, GOVERNMENT, HEALTHCARE, HOSPITALITY, INSURANCE, LEGAL, MANUFACTURING, NON_PROFIT, PROFESSIONAL, REAL_ESTATE, RETAIL, TECHNOLOGY, TRANSPORTATION

11. Campaign Registration

Register and manage campaigns for TCR carrier vetting.

package main

import (
	"fmt"
	"log"
	"os"

	"github.com/cloudcontactai/ccai-go/src/pkg/campaigns"
	"github.com/cloudcontactai/ccai-go/src/pkg/ccai"
	"github.com/joho/godotenv"
)

func boolPtr(b bool) *bool { return &b }

func main() {
	_ = godotenv.Load()

	client, err := ccai.NewClient(ccai.Config{
		ClientID: os.Getenv("CCAI_CLIENT_ID"),
		APIKey:   os.Getenv("CCAI_API_KEY"),
	})
	if err != nil {
		log.Fatalf("Failed to create client: %v", err)
	}

	// Create a campaign
	campaign, err := client.Campaigns.Create(campaigns.CampaignRequest{
		BrandID:          1,
		UseCase:          "MIXED",
		SubUseCases:      []string{"CUSTOMER_CARE", "TWO_FACTOR_AUTHENTICATION", "ACCOUNT_NOTIFICATION"},
		Description:      "Security codes and support messaging.",
		MessageFlow:      "Users opt-in via signup form at https://example.com/signup",
		HasEmbeddedLinks: boolPtr(true),
		HasEmbeddedPhone: boolPtr(false),
		IsAgeGated:       boolPtr(false),
		IsDirectLending:  boolPtr(false),
		OptInKeywords:    []string{"START"},
		OptInMessage:     "Welcome! Reply STOP to cancel.",
		OptInProofUrl:    "https://example.com/opt-in-proof.png",
		HelpKeywords:     []string{"HELP"},
		HelpMessage:      "For HELP email [email protected].",
		OptOutKeywords:   []string{"STOP"},
		OptOutMessage:    "STOP received. You are unsubscribed.",
		SampleMessages: []string{
			"Your code is 554321. Reply STOP to cancel.",
			"Your ticket has been updated. Reply HELP for info.",
		},
	})
	if err != nil {
		log.Fatalf("Failed to create campaign: %v", err)
	}
	fmt.Printf("Campaign created with ID: %d\n", campaign.ID)

	// Get a campaign by ID
	fetched, _ := client.Campaigns.Get(campaign.ID)
	fmt.Printf("Campaign use case: %s\n", fetched.UseCase)

	// List all campaigns
	campaignList, _ := client.Campaigns.List()
	fmt.Printf("Total campaigns: %d\n", len(campaignList))

	// Update a campaign (partial update)
	client.Campaigns.Update(campaign.ID, campaigns.CampaignRequest{
		Description: "Updated description.",
	})

	// Delete a campaign
	client.Campaigns.Delete(campaign.ID)
}

Use Cases: TWO_FACTOR_AUTHENTICATION, ACCOUNT_NOTIFICATION, CUSTOMER_CARE, DELIVERY_NOTIFICATION, FRAUD_ALERT, HIGHER_EDUCATION, LOW_VOLUME_MIXED, MARKETING, MIXED, POLLING_VOTING, PUBLIC_SERVICE_ANNOUNCEMENT, SECURITY_ALERT

MIXED and LOW_VOLUME_MIXED campaigns require 2-3 SubUseCases.

Sub-Use Cases: TWO_FACTOR_AUTHENTICATION, ACCOUNT_NOTIFICATION, CUSTOMER_CARE, DELIVERY_NOTIFICATION, FRAUD_ALERT, MARKETING, POLLING_VOTING

12. Project Structure

  • src/ - Source code
    • pkg/ - Package code

      • ccai/ - Main CCAI client package

        • client.go - Main CCAI client implementation
        • ccai.go - Type definitions and exports

      • sms/ - SMS-related functionality

        • models.go - Data models
        • sms.go - SMS service implementation
        • mms.go - MMS service implementation

      • email/ - Email-related functionality

        • models.go - Email data models
        • email.go - Email service implementation
    • examples/ - Example usage
    • email/ - Email example
  • .env - Environment variables
  • .env.example - Environment variables template

13. Features

  • Send email messages to single or multiple recipients
  • Send SMS messages to single or multiple recipients
  • Send MMS messages with images
  • Upload images to S3 with signed URLs
  • Variable substitution in messages
  • Progress tracking via callbacks
  • Environment variable support with .env files
  • Comprehensive error handling
  • Full test coverage

Try it yourself

See the full source code here.


Updated 16 days ago

Did this page help you?