Go SDK

The simpleemailapi-go package provides a fully typed, high-performance SDK for Go applications with real-time event streaming.

Language: Go 1.21+
Transport: HTTP/2 via Connect RPC

Installation

go get github.com/emailapi/sdk-go

Usage

Initialize the client with your API key and use the client.Send method.

package main

import (
    "context"
    "fmt"
    "log"

    emailapi "github.com/emailapi/sdk-go"
    v1 "github.com/emailapi/sdk-go/gen/v1"
)

func main() {
    client := emailapi.NewClient("sea_live_...")

    resp, err := client.Send(context.Background(), &v1.SendEmailRequest{
        From:    "hello@yourdomain.com",
        To:      []string{"user@example.com"},
        Subject: "Hello!",
        Body:    "Thanks for signing up.",
        Html:    "<p>Thanks for signing up.</p>",
    })
    if err != nil {
        log.Fatal(err)
    }

    fmt.Println("Email ID:", resp.Msg.Id)
}

The From address must belong to a domain you have verified.

Client Configuration

The NewClient function accepts optional configuration:

// Default usage
client := emailapi.NewClient("sea_live_...")

// With custom options
client := emailapi.NewClient("sea_live_...",
    emailapi.WithBaseURL("https://custom-endpoint.com"),
    emailapi.WithHTTPClient(customHTTPClient),
)

string

required

Your API Key, starting with sea_live_.

ClientOption

Sets a custom API endpoint. Defaults to https://api.simpleemailapi.dev.

ClientOption

Uses a custom http.Client for requests.

SendEmailRequest Fields

string

required

Sender email address. Must be from a verified domain.

[]string

required

List of primary recipient email addresses.

string

required

Email subject line.

string

Plain text content of the email.

string

HTML content of the email.

[]string

List of CC recipient email addresses.

[]string

List of BCC recipient email addresses.

[]*Attachment

List of files to attach.

string

Reply to a previous email using its Id from our response. We automatically resolve threading headers.

string

Raw Message-ID for threading (advanced). Use ReplyTo for simpler threading with our email IDs.

[]string

List of message IDs for threading context (advanced).

map[string]string

Custom key-value metadata returned in webhooks.

All emails are queued for reliable delivery with automatic retries. Use webhooks or event streaming to track delivery status.

Real-time Event Streaming

Stream email events with typed callbacks using OnReceive:

ctx, cancel := context.WithCancel(context.Background())
defer cancel()

client.OnReceive(ctx, emailapi.EventHandlers{
    OnDelivered: func(e *v1.EmailDeliveredEvent) {
        log.Println("Delivered to:", e.Recipients)
    },
    OnReplied: func(e *v1.EmailRepliedEvent) {
        log.Println("Reply from:", e.From)
    },
    OnBounced: func(e *v1.EmailBouncedEvent) {
        log.Println("Bounced:", e.BounceType, e.Recipients)
    },
    OnError: func(err error) {
        log.Println("Stream error:", err)
    },
})

The stream runs in a background goroutine and automatically reconnects with exponential backoff.

Available Event Handlers

Handler	Description
`OnSent`	Email accepted for delivery
`OnDelivered`	Email delivered to recipient’s mailbox
`OnBounced`	Email bounced (hard or soft)
`OnComplained`	Recipient marked email as spam
`OnRejected`	Email rejected before sending
`OnDelayed`	Email delivery delayed
`OnReplied`	Reply received to a sent email
`OnFailed`	Email sending failed permanently
`OnError`	Stream error occurred

Error Handling

The SDK provides structured error handling with typed error codes:

resp, err := client.Send(ctx, req)
if err != nil {
    if e := emailapi.ParseError(err); e != nil {
        switch {
        case e.Is(emailapi.ErrCodeDomainNotVerified):
            log.Println("Please verify your domain first")
        case e.IsCategory(emailapi.CategoryValidation):
            log.Println("Validation error on field:", e.Field)
        case e.IsCategory(emailapi.CategoryRateLimit):
            log.Println("Rate limited, retry later")
        default:
            log.Println("Error:", e.Message)
        }
    }
}

Error Categories

Category	Range	Description
`CategoryAuth`	1xx	Authentication errors
`CategoryAuthz`	2xx	Authorization errors
`CategoryValidation`	3xx	Validation errors
`CategoryNotFound`	4xx	Resource not found
`CategoryDomain`	5xx	Domain verification errors
`CategoryRateLimit`	6xx	Rate/usage limit errors
`CategoryInternal`	9xx	Internal server errors

Advanced Usage

Access underlying service clients for domain management:

// Domain management
domains, err := client.Domains.ListDomains(ctx, 
    connect.NewRequest(&v1.ListDomainsRequest{}))

// Direct email service access
resp, err := client.Emails.SendEmail(ctx, 
    connect.NewRequest(&v1.SendEmailRequest{...}))

Get Started

Domains

SDKs

Protocol Clients

Compliance

Receiving

Resources

Go SDK

Go SDK

Installation

Usage

Client Configuration

SendEmailRequest Fields

Real-time Event Streaming

Available Event Handlers

Error Handling

Error Categories

Advanced Usage

​Go SDK

​Installation

​Usage

​Client Configuration

​SendEmailRequest Fields

​Real-time Event Streaming

​Available Event Handlers

​Error Handling

​Error Categories

​Advanced Usage

Go SDK

Installation

Usage

Client Configuration

SendEmailRequest Fields

Real-time Event Streaming

Available Event Handlers

Error Handling

Error Categories

Advanced Usage