hanzo-gochimp

GoChimp3 is a Go client library for the MailChimp API v3.0.

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

MailChimp API key (format: <key>-<datacenter>, e.g., abc123-us6)
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 |

Related Skills

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