Golang SDK

The HiSend Go SDK (github.com/gethisend/hisend-go) provides a convenient wrapper around our REST APIs, carefully typed for Go projects. It's the recommended way to integrate HiSend into your Go backend or serverless environments.

Installation

You can install the SDK using the go get command:

go get github.com/gethisend/hisend-go

Initialization

Import the client and initialize it using the API Key generated in your project dashboard.

import "github.com/gethisend/hisend-go"

func main() {
	client := hisend.NewClient(hisend.Config{
		APIKey: "YOUR_API_KEY",
	})
	
	// Start using the client
}

Resources

The SDK is divided into resources, each handling a specific domain of the API. These are accessible via the initialized client.

Emails (client.Emails)

The Emails resource handles sending messages and fetching sent/received history.

Send(data SendEmailRequest)

Sends a single email.

subject := "Welcome to HiSend!"
htmlBody := "<h1>Welcome!</h1><p>We are glad to have you.</p>"
textBody := "Welcome! We are glad to have you."

result, err := client.Emails.Send(hisend.SendEmailRequest{
	From: "noreply@yourdomain.com",
	To:   []string{"user@example.com"},
	// Optional fields:
	Cc:  []string{"team@yourdomain.com"},
	Bcc: []string{"hidden@yourdomain.com"},
	Subject: &subject,
	HTML:    &htmlBody,
	Text:    &textBody,
})

SendBatch(data SendEmailBatchRequest)

Sends multiple emails in a single API request, useful for bulk messaging/newsletters.

batch := hisend.SendEmailBatchRequest{
	{From: "sales@test.com", To: []string{"a@test.com"}},
	{From: "sales@test.com", To: []string{"b@test.com"}},
}

result, err := client.Emails.SendBatch(batch)

List()

Returns a list of all emails (inbound and outbound) belonging to your project.

emails, err := client.Emails.List()
fmt.Printf("You have %d emails.\n", len(emails))

Get(id int)

Retrieves the details of a specific email by its ID.

email, err := client.Emails.Get(1234)
fmt.Println(*email.Subject)

Threads (client.Threads)

The Threads resource handles email conversations, grouping inbound and outbound replies into manageable topics.

List()

Returns all conversation threads for your project, ordered by the latest message time.

threads, err := client.Threads.List()

GetEmails(id int)

Returns all individual emails that belong to a specific Thread ID, in chronological order.

emailsInThread, err := client.Threads.GetEmails(849)
for _, msg := range emailsInThread {
	fmt.Printf("%s: %s\n", msg.From, msg.TextBody)
}

Domains (client.Domains)

The Domains resource manages the sender domains authorized for your project.

List()

Returns all domains registered to your project along with their verification statuses.

domains, err := client.Domains.List()

Get(id int)

Retrieves the details and verification status of a specific domain by its ID.

domain, err := client.Domains.Get(101)

Add(data AddDomainRequest)

Registers a new domain to your project. Note that it will remain pending until you verify its DNS records.

domain, err := client.Domains.Add(hisend.AddDomainRequest{
	Name: "newsletter.example.com",
})

Verify(id int)

Triggers a manual DNS check to verify if the required records (MX, TXT, CNAME) have been added to your registrar.

result, err := client.Domains.Verify(domain.ID)
fmt.Printf("Verification status: %s\n", result.VerificationStatus)

Delete(id int)

Removes a domain from your project.

err := client.Domains.Delete(domain.ID)

Routing (client.Routing)

The Routing resource manages how inbound emails are processed, allowing for Catch-All or exact-address routing.

List(domainID int)

Returns all inbound email routing rules configured for a specific domain.

routes, err := client.Routing.List(domainID)

Get(domainID int, id int)

Returns the details of a specific routing rule.

route, err := client.Routing.Get(domainID, routeID)

Create(domainID int, data CreateRoutingRequest)

Creates a new routing rule on a specific domain.

emailAddress := "support@yourdomain.com"
rule, err := client.Routing.Create(domainID, hisend.CreateRoutingRequest{
	Type:         "specific_address",
	EmailAddress: &emailAddress,
	EndpointIDs:  []int{102, 103},
})

Update(domainID int, id int, data UpdateRoutingRequest)

Updates an existing routing rule on a specific domain.

updatedRule, err := client.Routing.Update(domainID, rule.ID, hisend.UpdateRoutingRequest{
	EndpointIDs: []int{102},
})

Delete(domainID int, id int)

Deletes an existing inbound routing rule.

err := client.Routing.Delete(domainID, rule.ID)

Error Handling

All methods in the SDK return an error as the last return value. If the API request is rejected (e.g., HTTP 401 Unauthorized or HTTP 400 Bad Request), a descriptive error will be returned.

result, err := client.Emails.Send(req)
if err != nil {
	log.Fatalf("Failed to send email: %v", err)
}