Go SDK

Installation

          
          terminal
        
go get github.com/deadsimple/deadsimple-go

Quick Start

Create a client, make an inbox, and send an email:

          
          
          
          main.go
        

package main

import (
    "fmt"
    dse "github.com/deadsimple/deadsimple-go"
)

func main() {
    client := dse.NewClient("dse_your_api_key")

    inbox, _ := client.Inboxes.Create(&dse.CreateInboxInput{
        DisplayName: "My Agent",
    })
    fmt.Printf("Created: %s\n", inbox.Email)

    client.Messages.Send(&dse.SendMessageInput{
        InboxID:  inbox.InboxID,
        To:       []string{"user@example.com"},
        Subject:  "Hello from Go",
        TextBody: "Sent via the Dead Simple Go SDK.",
    })
}
        

Resources

Every API endpoint is available as a typed method on the client:

Resource	Methods
`client.Inboxes`	`Create`, `List`, `Get`, `Delete`, `BulkCreate`, `BulkDelete`
`client.Messages`	`Send`, `List`, `Get`, `Reply`, `Forward`
`client.Threads`	`List`, `Get`
`client.Webhooks`	`Create`, `List`, `Delete`
`client.Domains`	`Add`, `List`, `Verify`, `Delete`
`client.Usage`	`Get`

Context Support

Every method accepts a context.Context as the first argument for cancellation, timeouts, and tracing:

          
          
          
          context.go
        

import (
    "context"
    "time"
)

ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
defer cancel()

inboxes, err := client.Inboxes.ListWithContext(ctx)
if err != nil {
    // Handle timeout or cancellation
    log.Fatal(err)
}

for _, inbox := range inboxes.Data {
    fmt.Println(inbox.Email)
}
        

Error Handling

API errors are returned as typed *dse.APIError values with status code, error code, and message:

          
          
          
          errors.go
        

inbox, err := client.Inboxes.Get("inb_nonexistent")
if err != nil {
    var apiErr *dse.APIError
    if errors.As(err, &apiErr) {
        fmt.Printf("Status: %d, Code: %s, Message: %s\n",
            apiErr.StatusCode,
            apiErr.Code,
            apiErr.Message,
        )
    }
}
        

Webhook Verification

Verify incoming webhook signatures in your HTTP handler:

          
          
          
          webhook.go
        

import "net/http"

func webhookHandler(w http.ResponseWriter, r *http.Request) {
    body, _ := io.ReadAll(r.Body)
    signature := r.Header.Get("X-DSE-Signature")

    event, err := dse.VerifyWebhook(body, signature, webhookSecret)
    if err != nil {
        http.Error(w, "invalid signature", http.StatusUnauthorized)
        return
    }

    switch event.Type {
    case "message.received":
        fmt.Printf("New email from: %s\n", event.Data.From)
    }

    w.WriteHeader(http.StatusOK)
}
        

Configuration

The client accepts options for custom HTTP clients, base URLs, and timeouts:

          
          config.go
        
// Default client
client := dse.NewClient("dse_your_api_key")

// With options
client := dse.NewClient("dse_your_api_key",
    dse.WithBaseURL("https://api.your-domain.com"),
    dse.WithHTTPClient(&http.Client{Timeout: 10 * time.Second}),
)

// From environment variable (reads DSE_API_KEY)
client := dse.NewClientFromEnv()