Files
skills/public/hanzo-gochimp.md

7.9 KiB

Hanzo GoChimp3 - MailChimp API v3 Client for Go

Category: Hanzo Ecosystem Related Skills: hanzo/hanzo-commerce.md, hanzo/hanzo-commerce-api.md

Overview

GoChimp3 is a Go client library for the MailChimp API v3.0. It provides typed Go structs and methods for managing audiences (lists), members, campaigns, automations, e-commerce data, templates, segments, webhooks, and batch operations. Single package, zero external dependencies beyond net/http and encoding/json from the standard library. Test dependency on stretchr/testify.

Why GoChimp3?

  • Pure Go: Standard library HTTP client with configurable timeout and transport
  • Full API v3 coverage: Lists, members, campaigns, automations, e-commerce, templates, segments, webhooks, batch operations
  • Fluent API: Chain methods on response objects (e.g., list.CreateMember(req))
  • Typed errors: APIError struct with status, type, title, detail, and field-level errors
  • Configurable: Custom timeout, HTTP transport, debug mode with request/response dumping

Tech Stack

  • Language: Go (module requires Go 1.13+)
  • Module: github.com/hanzoai/gochimp3
  • Dependencies: github.com/stretchr/testify v1.5.1 (test only)
  • CI: Travis CI
  • License: MIT

OSS Base

Repo: hanzoai/gochimp3 (68 stars). Default branch: master.

When to use

  • Adding/removing/updating MailChimp list subscribers from Go services
  • Creating and sending email campaigns programmatically
  • Syncing e-commerce order/product/customer data to MailChimp
  • Managing automation workflows
  • Batch subscribing members with update-or-create semantics

Hard requirements

  1. MailChimp API key (format: <key>-<datacenter>, e.g., abc123-us6)
  2. Go 1.13+ (uses Go modules)

Quick reference

Item Value
Module github.com/hanzoai/gochimp3
Go version 1.13+
API version MailChimp API v3.0
Auth HTTP Basic Auth (API key)
Default branch master
License MIT
Repo github.com/hanzoai/gochimp3

One-file quickstart

package main

import (
 "fmt"
 "os"
 "time"

 "github.com/hanzoai/gochimp3"
)

func main() {
 client := gochimp3.New(os.Getenv("MAILCHIMP_API_KEY"))
 client.Timeout = 5 * time.Second

 // Get a list by ID
 list, err := client.GetList("YOUR_LIST_ID", nil)
 if err != nil {
 fmt.Println("Error:", err)
 os.Exit(1)
 }

 // Subscribe a member
 req := &gochimp3.MemberRequest{
 EmailAddress: "[email protected]",
 Status: "subscribed",
 MergeFields: map[string]interface{}{
 "FNAME": "Jane",
 "LNAME": "Doe",
 },
 }

 member, err := list.CreateMember(req)
 if err != nil {
 fmt.Println("Subscribe failed:", err)
 os.Exit(1)
 }
 fmt.Println("Subscribed:", member.EmailAddress)
}

Core Concepts

Architecture

gochimp3.New(apiKey) -> *API
 |
 |-- API.GetLists() -> *ListOfLists (paginated)
 |-- API.GetList(id) -> *ListResponse (has sub-methods)
 |-- API.GetCampaigns() -> *ListOfCampaigns
 |-- API.CreateCampaign()
 |-- API.SendCampaign()
 |
 ListResponse (fluent sub-API)
 |-- list.GetMembers()
 |-- list.CreateMember()
 |-- list.UpdateMember()
 |-- list.AddOrUpdateMember() (PUT - upsert)
 |-- list.DeleteMember()
 |-- list.DeleteMemberPermanent()
 |-- list.BatchSubscribeMembers()
 |-- list.GetInterestCategories()
 |-- list.GetMergeFields()
 |-- list.CreateMergeField()
 |
 Member (fluent sub-API)
 |-- member.GetActivity()
 |-- member.GetGoals()
 |-- member.GetNotes() / CreateNote() / UpdateNote()
 |-- member.GetTags() / UpdateTags()

API Client

The API struct is the entry point. It extracts the datacenter from the API key using a regex and constructs the endpoint URL (https://<dc>.api.mailchimp.com/3.0). All requests use HTTP Basic Auth with the key.

client := gochimp3.New("your-api-key-us6")
client.Timeout = 10 * time.Second // optional
client.Debug = true // dumps request/response
client.Transport = customTransport // optional custom transport

Query Parameters

All list/get methods accept typed query parameter structs:

  • BasicQueryParams -- Status, SortField, SortDirection, Fields, ExcludeFields
  • ExtendedQueryParams -- adds Count and Offset for pagination
  • ListQueryParams -- adds date filters and email filter
  • CampaignQueryParams -- adds type, status, date filters, list/folder IDs

Error Handling

API errors are returned as *APIError implementing the error interface:

member, err := list.CreateMember(req)
if err != nil {
 if apiErr, ok := err.(*gochimp3.APIError); ok {
 fmt.Println("Status:", apiErr.Status)
 fmt.Println("Detail:", apiErr.Detail)
 for _, e := range apiErr.Errors {
 fmt.Println("Field:", e.Field, "Message:", e.Message)
 }
 }
}

Member ID by Email

MailChimp uses MD5 hash of lowercase email as member ID. The library provides a helper:

member := api.MemberForApiCalls("list-id", "[email protected]")
// member.ID is now the MD5 hash, ready for API calls

Directory structure

github.com/hanzoai/gochimp3/
 api.go # API client, HTTP transport, request/response handling
 api_test.go # Client tests
 common_types.go # APIError, QueryParams, Link, Address, Contact, etc.
 lists.go # Lists CRUD, abuse reports, activity, clients, growth history,
 # interest categories, interests, batch subscribe, merge fields
 members.go # Members CRUD, activity, goals, notes, tags
 campaigns.go # Campaigns CRUD, send test, send, content updates
 automations.go # Automation workflows, emails, queues
 automation_workflows.go # Workflow-level operations
 ecommerce.go # Stores, products, variants, orders, carts, customers
 segments.go # List segments CRUD, batch modify
 templates.go # Templates CRUD
 template_folders.go # Template folder CRUD
 campaign_folders.go # Campaign folder CRUD
 batches.go # Batch operations
 webhooks.go # Webhook CRUD on lists
 search.go # Search members
 events.go # Member events
 events_test.go # Events tests
 root.go # API root info
 json.go # JSON helper (custom time parsing)
 go.mod # Module definition
 go.sum # Dependency checksums

API Coverage

Resource Methods
Lists GetLists, GetList, CreateList, UpdateList, DeleteList
Members GetMembers, GetMember, CreateMember, UpdateMember, AddOrUpdateMember, DeleteMember, DeleteMemberPermanent, BatchSubscribeMembers
Campaigns GetCampaigns, GetCampaign, CreateCampaign, UpdateCampaign, DeleteCampaign, SendTestEmail, SendCampaign, GetCampaignContent, UpdateCampaignContent
Automations GetAutomations, GetAutomation, PauseAutomation, StartAutomation
E-commerce Stores, Products, Variants, Orders, Carts, Customers (full CRUD)
Segments GetSegments, GetSegment, CreateSegment, UpdateSegment, DeleteSegment, BatchModifySegment
Templates GetTemplates, GetTemplate, CreateTemplate, UpdateTemplate, DeleteTemplate
Webhooks GetWebhooks, GetWebhook, CreateWebhook, DeleteWebhook
Merge Fields GetMergeFields, GetMergeField, CreateMergeField
Interest Categories GetInterestCategories, GetInterestCategory, CreateInterestCategory, UpdateInterestCategory, DeleteInterestCategory
Tags GetTags, UpdateTags (on members)
Search SearchMembers

Troubleshooting

Issue Cause Solution
"No ID provided on list" Using ListResponse without ID Use api.GetList(id) or api.NewListResponse(id)
Wrong datacenter API key format incorrect Key must be <key>-<dc> (e.g., abc-us6)
401 Unauthorized Invalid API key Verify key in MailChimp account settings
Timeout errors Default no timeout Set client.Timeout = 10 * time.Second
Rate limits (429) Too many requests MailChimp allows 10 concurrent connections; add backoff
  • hanzo/hanzo-commerce.md - E-commerce platform (uses MailChimp for email marketing)
  • hanzo/hanzo-commerce-api.md - Commerce API (subscriber sync)

Last Updated: 2026-03-13 Category: Hanzo Ecosystem Related: mailchimp, email, marketing, go, api-client Prerequisites: Go 1.13+, MailChimp API key