Hanzo GoChimp3

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, seg...

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: "user@example.com",
        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", "user@example.com")
// 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)

On this page