> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wazobiamail.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Go SDK

> Install the official WazobiaMail Go SDK with go get, then send transactional email, manage domains and verify webhooks.

The official Go SDK is a typed, zero-dependency client for Go 1.22+. It uses `context.Context` for cancellation and deadlines, exports typed request/response models, and is safe for concurrent use.

> [card] [pkg.go.dev](https://pkg.go.dev/github.com/WazobiaMail/wazobiamail-go)
>
> `github.com/WazobiaMail/wazobiamail-go`

> [card] [Source](https://github.com/WazobiaMail/wazobiamail-go)
>
> WazobiaMail/wazobiamail-go

## At a glance

| | |
| - | - |
| Runtime | Go 1.22+ |
| Dependencies | None |
| Package | `github.com/WazobiaMail/wazobiamail-go` |
| Import alias | `wazobiamail` |
| Install | `go get github.com/WazobiaMail/wazobiamail-go@v0.1.0` |
| Source | [github.com/WazobiaMail/wazobiamail-go](https://github.com/WazobiaMail/wazobiamail-go) |

## Install

```bash theme={null}
go get github.com/WazobiaMail/wazobiamail-go@v0.1.0
```

```go theme={null}
import wazobiamail "github.com/WazobiaMail/wazobiamail-go"
```

## Configure

```go theme={null}
client, err := wazobiamail.NewClient("wz_live_...")
if err != nil {
    log.Fatal(err)
}

// Or resolve WAZOBIA_API_KEY / WAZOBIAMAIL_API_KEY:
client, err = wazobiamail.NewClientFromEnv()

// Options:
client, err = wazobiamail.NewClient(
    "wz_live_...",
    wazobiamail.WithTimeout(15*time.Second),
    wazobiamail.WithUserAgent("my-app/2.0"),
)
```

The SDK sends `X-API-Key`; use `WithAccessToken` for an account Bearer token. Pass a `context.Context` to every call.

## Send your first email

```go theme={null}
package main

import (
    "context"
    "fmt"
    "log"

    wazobiamail "github.com/WazobiaMail/wazobiamail-go"
)

func main() {
    client, err := wazobiamail.NewClient("wz_live_...")
    if err != nil {
        log.Fatal(err)
    }

    resp, err := client.Messages.Send(context.Background(), wazobiamail.SendMessageRequest{
        To:      []string{"customer@example.com"},
        From:    "Acme <hello@mail.example.com>",
        Subject: "Your order shipped",
        HTML:    "<p>Your order is on its way.</p>",
        Text:    "Your order is on its way.",
    })
    if err != nil {
        log.Fatal(err)
    }

    fmt.Println(resp.Data.Result.TrackingID)
}
```

Set `IdempotencyKey` in `SendMessageRequest` for safe retries. Use `SendWithAttachments` for binary files, or `UploadAttachment` to get a public URL first.

## What you can do

* `Messages` — send, multipart attachments, tracking/logs and spam checks.
* `Domains` — list/create/update/delete, DNS records, verification and Cloudflare DNS.
* `Mailboxes` — provisioning, credentials, storage and headless inbox messages.
* `APIKeys`, `SMTP` — scoped keys, relays and SMTP access.
* `Billing`, `Units`, `Plans`, `Status` — invoices, subscriptions, credits, limits and account health.
* `Support`, `Templates` — support threads and Enterprise templates.
* `Webhooks` — HMAC SHA-256 signature verification without a network call.

## Spam-check scores

`Messages.SpamCheck` returns a penalty `Score`, a `Threshold`, an `IsSpam` flag and an inverse `DeliverabilityScore` (0–100, higher is better).

| `Score` | `Rating` | `IsSpam` | `DeliverabilityScore` | Decision |
| - | - | - | - | - |
| `0.0 – 1.9` | `low_risk` | `false` | `81 – 100` | **Okay to send.** |
| `2.0 – 4.9` | `moderate_risk` | `false` | `51 – 80` | **Review first.** Fix high-point rules. |
| `5.0 +` | `high_risk` | `true` | `0 – 50` | **Do not send.** Fix and re-check. |

`IsSpam` is true when `Score >= Threshold`; read `Threshold` from the response instead of hard-coding `5.0`. See [Spam and deliverability scores](https://docs.wazobiamail.com/docs/guides/spam-check.md).

## Webhooks

```go theme={null}
signature := r.Header.Get(wazobiamail.WebhookSignatureHeader)

var event struct {
    Type string `json:"type"`
    Data struct {
        TrackingID string `json:"trackingId"`
    } `json:"data"`
}

if err := client.Webhooks.ConstructEvent(body, signature, secret, &event); err != nil {
    if errors.Is(err, wazobiamail.ErrInvalidWebhookSignature) {
        http.Error(w, "invalid signature", http.StatusUnauthorized)
        return
    }
    http.Error(w, "bad payload", http.StatusBadRequest)
    return
}
```

Always verify the **raw** request body. `VerifySignature` accepts a hex HMAC SHA-256 value with an optional `sha256=` prefix.

## Errors

```go theme={null}
var apiErr *wazobiamail.APIError
if errors.As(err, &apiErr) {
    switch {
    case apiErr.IsValidation():
        fmt.Println(apiErr.Errors)
    case apiErr.IsRateLimited():
        time.Sleep(apiErr.RetryAfter)
    }
}
```

`APIError` exposes `StatusCode`, `Message`, `Code`, `Errors`, `Body` and `RetryAfter`.

## Concurrency

A `*Client` is safe for concurrent use and holds an `*http.Client`; reuse one instance across goroutines. Each request accepts a context, so cancel or time out individual calls without recreating the client.

## Links

* [pkg.go.dev](https://pkg.go.dev/github.com/WazobiaMail/wazobiamail-go)
* [GitHub](https://github.com/WazobiaMail/wazobiamail-go)
* [Full README](https://github.com/WazobiaMail/wazobiamail-go#readme)
* [All official SDKs](https://docs.wazobiamail.com/docs/guides/sdks.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.