📬 go-instantly

Unofficial Golang Library for the Instantly.ai API (V2).

`CI / CD`		`Quality`
`Security`		`Community`

`Project Navigation`

🚀 `Installation`	🧪 `Examples & Tests`	📚 `Documentation`
🤝 `Contributing`	🛠️ `Code Standards`	⚡ `Benchmarks`
🤖 `AI Usage`	⚖️ `License`	👥 `Maintainers`

📦 Installation

go-instantly requires a supported release of Go.

go get github.com/mrz1836/go-instantly

💡 Usage

This library targets the Instantly.ai API V2 only. V2 is not backwards compatible with V1 and uses its own credentials — a V1 key will not authenticate against V2, so create a V2 API key in your workspace settings and pass it to NewClient. Every request is then authenticated with an Authorization: Bearer <key> header against https://api.instantly.ai.

The SDK is organized AWS-SDK-v2 style: a tiny root package holds the shared Client, and each API resource lives in its own subpackage (email, campaign, account, …). Construct the client once and hand it to a resource service. Importing a resource pulls in only that resource plus the root package and the standard library — never testify or the other resources.

package main

import (
	"context"
	"log"

	"github.com/mrz1836/go-instantly"
	"github.com/mrz1836/go-instantly/email"
)

func main() {
	client := instantly.NewClient("[API-KEY]")
	emails := email.New(client)

	err := emails.SendTest(context.Background(), email.SendTestRequest{
		EAccount:           "sender@example.com",
		ToAddressEmailList: "recipient@example.com",
		Subject:            "Testing the sending account",
		Body: email.Body{
			HTML: "<p>Hello from go-instantly.</p>",
			Text: "Hello from go-instantly.",
		},
	})
	if err != nil {
		log.Fatal(err)
	}
}

List endpoints take functional options, so only the filters you actually pass are sent:

page, err := emails.List(ctx,
	email.WithLimit(50),
	email.WithIsUnread(true),
	email.WithMode(email.ModeFocused),
)

Pagination is cursor based. List returns a single page, and ListIter walks every page for you as a range-over-func iterator:

for message, err := range emails.ListIter(ctx, email.WithIsUnread(true)) {
	if err != nil {
		return err
	}
	log.Printf("%s: %s", message.ID, message.Subject)
}

Some endpoints report a failure inside an otherwise successful HTTP 200 response. This library turns those into real errors, so err != nil catches every failure regardless of which shape it arrived in:

var apiErr *instantly.APIError
if errors.As(err, &apiErr) && apiErr.Code == instantly.ErrCodeAccountAuthError {
	// the sending account failed to authenticate
}

📚 Documentation

View the generated documentation, or the Instantly.ai API reference for endpoint details, scopes, and per-endpoint rate limits.

Heads up! go-instantly is intentionally light on dependencies. The only external package it uses is the excellent testify suite—and that's just for our tests. You can drop this library into your projects without dragging along extra baggage.

Supported API Coverage

Coverage is built one resource at a time against the Instantly V2 OpenAPI spec — 171 operations across 127 endpoints in 28 resource groups. Each resource is its own Go package (AWS-SDK-v2 style). 171 / 171 operations · 28 / 28 resources ship today (Email, Account, Account-Campaign Mappings, Campaign, Lead, Lead List, Lead Label, Campaign Subsequence, Email Verification, Inbox Placement Test, Inbox Placement Analytics, Inbox Placement Report, SuperSearch Enrichment, Webhook, Webhook Event, Workspace, Workspace Member, Workspace Group Member, Workspace Billing, Block List Entry, Custom Tag, Custom Tag Mapping, API Key, Audit Log, Background Job, CRM Actions, OAuth, DFY Email Account Order) — the SDK now covers the entire Instantly.ai V2 API.

Every V2 resource now ships — there is no remaining planned coverage.

Notes on the counts. The Analytics area (7 operations) is cross-cutting — 3 endpoints live under Account and 4 under Campaign, so they are counted within those resources rather than as a separate group. Three additional tags — CustomPromptTemplate, EmailTemplate, and SalesFlow — are declared in the V2 API but currently expose no public endpoints.

Adding a resource? Follow the durable recipe in docs/adding-a-resource.md — the email package is the reference implementation.

Client Configuration (Functional Options)

The client is immutable after construction: configure it once with functional options. This is safer than mutating shared state and is the idiomatic Go pattern. Available options:

Option	Purpose
`WithHTTPClient(*http.Client)`	Custom transport, proxy, or timeout
`WithBaseURL(string)`	Point at a test server or gateway
`WithUserAgent(string)`	Set the `User-Agent` header
`WithHTTPHeader(key, value)`	Add an extra header to every request

package main

import (
    "net/http"
    "time"

    "github.com/mrz1836/go-instantly"
)

// ....

client := instantly.NewClient("[API-KEY]",
    instantly.WithHTTPClient(&http.Client{Timeout: 30 * time.Second}),
    instantly.WithUserAgent("my-app/1.0"),
)

// ...

Need an endpoint the typed resource packages do not wrap yet? The low-level plumbing is exported as an escape hatch: client.Get, client.Post, client.Patch, client.Put, client.Delete, client.Do, and client.DoRaw (raw bytes, for CSV and other non-JSON responses).

Development Setup (Getting Started)

Install MAGE-X build tool for development:

# Install MAGE-X for development and building
go install github.com/mrz1836/mage-x/cmd/magex@latest
magex update:install

Library Deployment

This project uses goreleaser for streamlined binary and library deployment to GitHub. To get started, install it via:

brew install goreleaser

The release process is defined in the .goreleaser.yml configuration file.

Then create and push a new Git tag using:

magex version:bump bump=patch push=true branch=master

This process ensures consistent, repeatable releases with properly versioned artifacts and citation metadata.

Build Commands

View all build commands

magex help

GitHub Workflows

All workflows are driven by modular configuration in .github/env/ — no YAML editing required.

View all workflows and the control center →

Updating Dependencies

To update all dependencies (Go modules, linters, and related tools), run:

magex deps:update

This command ensures all dependencies are brought up to date in a single step, including Go modules and any managed tools. It is the recommended way to keep your development environment and CI in sync with the latest versions.

🧪 Examples & Tests

All unit tests and fuzz tests run via GitHub Actions and use Go version 1.25.x. View the configuration file.

Run all tests (fast):

magex test

Run all tests with race detector (slower):

magex test:race

Browse the runnable usage samples in examples/examples.go.

Note: the test suite runs entirely against an in-repo mock router. No test contacts the live Instantly.ai API, and the examples file is illustrative — it is compiled, never executed by CI.

⚡ Benchmarks

Run the Go benchmarks:

magex bench

📊 Performance Results

A benchmark suite now covers the hot paths — query encoding and path building (Query.Encode, BuildPath), the response-error probe (checkResponse), cursor iteration (Iterate), the reusable list helpers (JoinPath, ApplyOptions), and a representative resource decode and round-trip (CampaignDecode, CampaignGet). Run magex bench to measure them on your own hardware; numbers vary by machine, so they are reproduced locally rather than pinned here.

🛠️ Code Standards

Read more about this Go project's code standards.

🤖 AI Usage & Assistant Guidelines

Read the AI Usage & Assistant Guidelines for details on how AI is used in this project and how to interact with the AI assistants.

👥 Maintainers


MrZ

🤝 Contributing

View the contributing guidelines and please follow the code of conduct.

How can I help?

All kinds of contributions are welcome 🙌! The most basic way to show your support is to star 🌟 the project, or to raise issues 💬. You can also support this project by becoming a sponsor on GitHub 👏 or by making a bitcoin donation to ensure this journey continues indefinitely! 🚀

Name		Name	Last commit message	Last commit date
.github		.github
.vscode		.vscode
account		account
accountcampaign		accountcampaign
apikey		apikey
auditlog		auditlog
backgroundjob		backgroundjob
blocklist		blocklist
campaign		campaign
crm		crm
customtag		customtag
customtagmapping		customtagmapping
dfy		dfy
docs		docs
email		email
emailverification		emailverification
examples		examples
inboxanalytics		inboxanalytics
inboxreport		inboxreport
inboxtest		inboxtest
internal/instantlytest		internal/instantlytest
lead		lead
leadlabel		leadlabel
leadlist		leadlist
oauth		oauth
subsequence		subsequence
supersearch		supersearch
webhook		webhook
webhookevent		webhookevent
workspace		workspace
workspacebilling		workspacebilling
workspacegroup		workspacegroup
workspacemember		workspacemember
.cursorrules		.cursorrules
.devcontainer.json		.devcontainer.json
.dockerignore		.dockerignore
.editorconfig		.editorconfig
.gitattributes		.gitattributes
.gitignore		.gitignore
.gitleaksignore		.gitleaksignore
.gitpod.yml		.gitpod.yml
.golangci.json		.golangci.json
.goreleaser.yml		.goreleaser.yml
LICENSE		LICENSE
README.md		README.md
bench_test.go		bench_test.go
codecov.yml		codecov.yml
doc.go		doc.go
enums.go		enums.go
errors.go		errors.go
errors_test.go		errors_test.go
example_test.go		example_test.go
go.mod		go.mod
go.sum		go.sum
instantly.go		instantly.go
instantly_fuzz_test.go		instantly_fuzz_test.go
instantly_test.go		instantly_test.go
iterate.go		iterate.go
iterate_test.go		iterate_test.go
list.go		list.go
list_test.go		list_test.go
query.go		query.go
query_test.go		query_test.go
t3.json		t3.json

Navigation Menu

Repository navigation

About

Repository files navigation

📬 go-instantly

`Project Navigation`

📦 Installation

💡 Usage

📚 Documentation

🧪 Examples & Tests

⚡ Benchmarks

📊 Performance Results

🛠️ Code Standards

🤖 AI Usage & Assistant Guidelines

👥 Maintainers

🤝 Contributing

How can I help?

📝 License

About

Releases

Sponsor this project

Packages

Used by

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

📬 go-instantly

Project Navigation

📦 Installation

💡 Usage

📚 Documentation

🧪 Examples & Tests

⚡ Benchmarks

📊 Performance Results

🛠️ Code Standards

🤖 AI Usage & Assistant Guidelines

👥 Maintainers

🤝 Contributing

How can I help?

📝 License

About

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

Watchers

Forks

Releases

Sponsor this project

Packages

Used by

Contributors

Languages

`Project Navigation`