> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lettr.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Getting Started
> Get started sending transactional emails from Go with the official Lettr SDK, featuring type-safe calls and context support.
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](https://cursor.com/link/prompt?text=Help%20me%20add%20a%20Lettr%20sending%20example%20for%20Go%20using%20github.com%2Flettr-com%2Flettr-go%2C%20or%20migrate%20my%20current%20Go%20sending%20solution%20to%20Lettr%20using%20these%20docs%3A%20https%3A%2F%2Fdocs.lettr.com%2Fquickstart%2Fgo%2Fquickstart)
## 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](/quickstart/smtp/introduction) or make direct [HTTP API](/api-reference/emails/send-email) calls.
## Prerequisites
Before you begin, make sure you have:
Create an API key in the Lettr dashboard
Add and verify your sending domain
You'll also need:
* **Go 1.21 or later** installed
* A verified sending domain in your [Lettr dashboard](https://app.lettr.com/domains)
## Quick Setup
Get started in three quick steps: install, configure, and send.
```bash theme={null}
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.
```go theme={null}
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.
```go theme={null}
resp, err := client.Emails.Send(ctx, &lettr.SendEmailRequest{
From: "sender@yourdomain.com",
To: []string{"recipient@example.com"},
Subject: "Hello from Lettr",
Html: "Hello!
This is a test email.
",
})
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](https://app.lettr.com/domains) 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:
```go theme={null}
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:
```bash theme={null}
go get github.com/joho/godotenv
```
Create a `.env` file:
```env theme={null}
LETTR_API_KEY=lttr_your_api_key_here
```
Load it in your application:
```go theme={null}
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:
```go theme={null}
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:
```go theme={null}
resp, err := client.Emails.Send(ctx, &lettr.SendEmailRequest{
From: "notifications@yourdomain.com",
To: []string{"user@example.com"},
Subject: "Welcome to our service",
Html: "Welcome!
Thanks for signing up.
",
})
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:
```go theme={null}
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: "Hello!
",
})
```
### Plain Text Email
Send a plain text email without HTML:
```go theme={null}
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:
```go theme={null}
resp, err := client.Emails.Send(ctx, &lettr.SendEmailRequest{
From: "notifications@yourdomain.com",
To: []string{"user@example.com"},
Subject: "Multipart email",
Html: "Hello!
This is the HTML version.
",
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:
Manage Lettr templates and merge tags
Add, verify, and manage sending domains
Manage webhook endpoints for delivery and engagement events
Lists, contacts, topics, properties, and segments
List, send, and schedule campaigns
## What's Next
Learn about attachments, templates, tracking, and more
Complete API documentation
Email deliverability tips