Getting Started

Send transactional emails from your Go applications using the official Lettr Go SDK. The SDK provides a type-safe, idiomatic Go interface for the Lettr API with full context support and structured error handling. Using Cursor? Jump straight in using this prompt

Why Use the Go SDK?

Rather than making raw HTTP requests, the SDK provides:

Type-safe API — Full struct definitions with proper types and validation
Context support — All methods accept context.Context for timeouts and cancellation
Structured errors — Typed error responses with detailed validation messages
Minimal dependencies — Only depends on Go’s standard library and net/http
Idiomatic Go — Follows Go conventions and patterns you already know

If you prefer not to use the SDK, you can also send emails via SMTP or make direct HTTP API calls.

Prerequisites

Before you begin, make sure you have:

API Key

Create an API key in the Lettr dashboard

Verified Domain

Add and verify your sending domain

You’ll also need:

Go 1.21 or later installed
A verified sending domain in your Lettr dashboard

Quick Setup

Get started in three quick steps: install, configure, and send.

Install the SDK

go get github.com/lettr-com/lettr-go

The SDK has minimal dependencies and only requires Go’s standard library. It works with Go 1.21+ and follows semantic versioning.

Create a client

package main

import (
    "context"
    "log"

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

func main() {
    client := lettr.NewClient("your-api-key")

    // Verify the client is configured correctly
    ctx := context.Background()
    auth, err := client.ValidateAPIKey(ctx)
    if err != nil {
        log.Fatal(err)
    }

    log.Printf("Connected to Lettr (Team ID: %s)", auth.Data.TeamID)
}

Store your API key in environment variables, never hardcode it. API keys use the lttr_ prefix followed by 64 hexadecimal characters.

Send your first email

resp, err := client.Emails.Send(ctx, &lettr.SendEmailRequest{
    From:    "sender@yourdomain.com",
    To:      []string{"recipient@example.com"},
    Subject: "Hello from Lettr",
    Html:    "<h1>Hello!</h1><p>This is a test email.</p>",
})
if err != nil {
    log.Fatal(err)
}

log.Printf("Email sent! Request ID: %s, Accepted: %d",
    resp.Data.RequestID, resp.Data.Accepted)

The response includes a RequestID for tracking and the number of accepted recipients.

The sender domain must be verified in your Lettr dashboard before you can send emails. Sending from an unverified domain returns a validation error.

Configuration

Environment Variables

Read your API key from an environment variable:

package main

import (
    "os"

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

func main() {
    apiKey := os.Getenv("LETTR_API_KEY")
    if apiKey == "" {
        panic("LETTR_API_KEY environment variable is required")
    }

    client := lettr.NewClient(apiKey)
}

Using godotenv

Load environment variables from a .env file using the godotenv package:

go get github.com/joho/godotenv

Create a .env file:

LETTR_API_KEY=lttr_your_api_key_here

Load it in your application:

package main

import (
    "log"
    "os"

    "github.com/joho/godotenv"
    lettr "github.com/lettr-com/lettr-go"
)

func main() {
    // Load .env file
    if err := godotenv.Load(); err != nil {
        log.Printf("Warning: .env file not found: %v", err)
    }

    client := lettr.NewClient(os.Getenv("LETTR_API_KEY"))
}

Add .env to your .gitignore file to prevent accidentally committing your API key to version control.

Custom HTTP Client

Use a custom HTTP client with custom timeouts or transport settings:

import (
    "net/http"
    "time"

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

// Create a custom HTTP client with a 30-second timeout
httpClient := &http.Client{
    Timeout: 30 * time.Second,
}

client := lettr.NewClientWithHTTPClient("your-api-key", httpClient)

Sending Emails

Basic HTML Email

Send a simple HTML email:

resp, err := client.Emails.Send(ctx, &lettr.SendEmailRequest{
    From:    "notifications@yourdomain.com",
    To:      []string{"user@example.com"},
    Subject: "Welcome to our service",
    Html:    "<h1>Welcome!</h1><p>Thanks for signing up.</p>",
})
if err != nil {
    log.Printf("Failed to send email: %v", err)
    return
}

log.Printf("Email sent successfully (Request ID: %s)", resp.Data.RequestID)

With Display Name

Add a friendly display name to the sender address:

resp, err := client.Emails.Send(ctx, &lettr.SendEmailRequest{
    From:     "notifications@yourdomain.com",
    FromName: "Acme Corp",
    To:       []string{"user@example.com"},
    Subject:  "Welcome to Acme",
    Html:     "<h1>Hello!</h1>",
})

Plain Text Email

Send a plain text email without HTML:

resp, err := client.Emails.Send(ctx, &lettr.SendEmailRequest{
    From:    "notifications@yourdomain.com",
    To:      []string{"user@example.com"},
    Subject: "Plain text email",
    Text:    "This is a plain text email.\n\nIt has no HTML formatting.",
})

Multipart Emails (HTML + Text)

Send both HTML and plain text versions for maximum compatibility:

resp, err := client.Emails.Send(ctx, &lettr.SendEmailRequest{
    From:    "notifications@yourdomain.com",
    To:      []string{"user@example.com"},
    Subject: "Multipart email",
    Html:    "<h1>Hello!</h1><p>This is the HTML version.</p>",
    Text:    "Hello!\n\nThis is the plain text version.",
})

Providing both HTML and plain text ensures your emails are readable in all email clients, including text-only clients and accessibility tools.

Explore the SDK

Beyond sending, the SDK manages every Lettr resource:

Templates

Manage Lettr templates and merge tags

Domains

Add, verify, and manage sending domains

Webhooks

Manage webhook endpoints for delivery and engagement events

Audience

Lists, contacts, topics, properties, and segments

Campaigns

List, send, and schedule campaigns

What’s Next

Advanced Features

Learn about attachments, templates, tracking, and more

API Reference

Complete API documentation

Best Practices

Email deliverability tips

​Why Use the Go SDK?

​Prerequisites

API Key

Verified Domain

​Quick Setup

​Configuration

​Environment Variables

​Using godotenv

​Custom HTTP Client

​Sending Emails

​Basic HTML Email

​With Display Name

​Plain Text Email

​Multipart Emails (HTML + Text)

​Explore the SDK

Templates

Domains

Webhooks

Audience

Campaigns

​What’s Next

Advanced Features

API Reference

Best Practices

Why Use the Go SDK?

Prerequisites

Quick Setup

Configuration

Environment Variables

Using godotenv

Custom HTTP Client

Sending Emails

Basic HTML Email

With Display Name

Plain Text Email

Multipart Emails (HTML + Text)

Explore the SDK

What’s Next