Skip to main content

​
Prerequisites

​
Installation

Install the useSend Go SDK: 
go get github.com/usesend/usesend-go

​
Initialize

Create a new client using your API key. 
package main

import (
    "context"
    "log"

    usesend "github.com/usesend/usesend-go"
)

func main() {
    client, err := usesend.NewClient("us_12345")
    if err != nil {
        log.Fatal(err)
    }
}
API keys can also be supplied via the USESEND_API_KEY environment variable.

​
Self-Hosted Setup

If you are running a self-hosted version of useSend, provide the base URL using WithBaseURL. 
client, err := usesend.NewClient(
    "us_12345",
    usesend.WithBaseURL("https://app.usesend.com"),
)
if err != nil {
    log.Fatal(err)
}
The base URL should be the root domain only. Do not include /api/v1, as the SDK manages API paths internally.

​
Options

  • WithBaseURL(url string): Override the base API URL (e.g. for self-hosting)
  • WithHTTPClient(*http.Client): Provide a custom HTTP client
The default HTTP client uses a 30s timeout. Requests include a User-Agent: usesend-go header.

​
Sending Emails

resp, errResp, err := client.Emails.Send(
    context.Background(),
    usesend.SendEmailPayload{
        To:      []string{"[email protected]"},
        From:    "[email protected]",
        Subject: "useSend email",
        HTML:    "<p>useSend is the best open source product to send emails</p>",
        Text:    "useSend is the best open source product to send emails",
        Headers: map[string]string{
            "X-Campaign": "welcome",
        },
    },
)

if err != nil {
    log.Fatal(err)
}

if errResp != nil {
    log.Fatalf("API error: %s", errResp.Message)
}

log.Printf("Email queued with ID: %s", resp.EmailID)
Custom headers are forwarded as-is. useSend only manages the X-Usesend-Email-ID and References headers.

​
Managing Contacts

​
Get Contact Book ID

Retrieve the contact book ID from the useSend dashboard.

​
Create Contacts

contact, apiErr, err := client.Contacts.Create(
    context.Background(),
    "contactBook_123",
    usesend.CreateContactPayload{
        Email:     "[email protected]",
        FirstName: "Koushik",
        LastName:  "KM",
    },
)

if err != nil {
    log.Fatal(err) // transport error
}

if apiErr != nil {
    log.Fatalf("API error: %s", apiErr.Message)
}

log.Printf("Contact ID: %s", contact.ContactID)

​
Update Contacts

contact, apiErr, err := client.Contacts.Update(
    context.Background(),
    "contactBook_123",
    "contact_456",
    usesend.UpdateContactPayload{
        FirstName: "Koushik",
        LastName:  "KM",
    },
)

if err != nil {
    log.Fatal(err)
}

if apiErr != nil {
    log.Fatalf("API error: %s", apiErr.Message)
}