Go SDK

The jetemail-go module is the official Go SDK for JetEmail transactional email (MIT license, Go 1.21+, no third-party dependencies). Create a transactional API key in the dashboard: Outbound → Keys → Add API key. Use that key with the SDK.

Installation

go get github.com/jetemail/jetemail-go

Module path: github.com/jetemail/jetemail-go. Source on GitHub: jetemail/jetemail-go.

Quick start

package main

import (
    "fmt"
    "log"

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

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

    resp, err := client.Emails.Send(&jetemail.SendEmailRequest{
        From:    "Your App <hello@yourdomain.com>",
        To:      []string{"user@example.com"},
        Subject: "Welcome!",
        Html:    "<h1>Welcome!</h1>",
    })
    if err != nil {
        log.Fatal(err)
    }

    fmt.Println(resp.Id)
}

Use a From address on a verified domain (see Getting started).

Creating a client

// API key only (30 second HTTP timeout by default)
client := jetemail.NewClient("your-transactional-api-key")

// With your own *http.Client (note the argument order)
httpClient := &http.Client{Timeout: 60 * time.Second}
client := jetemail.NewCustomClient(httpClient, "your-transactional-api-key")

// Custom base URL
client.BaseURL = "https://api.jetemail.com"

Both constructors return a *jetemail.Client. Its ApiKey, BaseURL and HTTPClient fields are exported, so they can be changed after creation. The client exposes two services:

Service	Field	Description
Emails	`client.Emails`	Send a single email
Batch	`client.Batch`	Send up to 100 emails in one request

Every Send method has a SendWithContext(ctx, ...) variant that takes a context.Context; Send uses context.Background().

`client.Emails.Send(*SendEmailRequest)`

Send a single email. Returns (*SendEmailResponse, error).

Field	Required	Description
`From`	✓	Sender `string`, e.g. `"Name <email@domain.com>"`
`To`	✓	`[]string` of recipients (max 50)
`Subject`	✓	Subject line
`Html`	*	HTML body (need `Html` and/or `Text`)
`Text`	*	Plain text (need `Html` and/or `Text`)
`Cc`, `Bcc`, `ReplyTo`		`[]string` of recipients (max 50 each)
`Headers`		Custom headers, `map[string]string`
`Attachments`		`[]jetemail.Attachment` (max 40MB total)
`Eu`		`true` to restrict processing to EU infrastructure

resp, err := client.Emails.Send(&jetemail.SendEmailRequest{
    From:    "App <noreply@example.com>",
    To:      []string{"user@example.com"},
    Subject: "Order Confirmation",
    Html:    "<p>Your order has been confirmed.</p>",
    Text:    "Your order has been confirmed.",
    Cc:      []string{"manager@example.com"},
    Bcc:     []string{"archive@example.com"},
    ReplyTo: []string{"support@example.com"},
    Headers: map[string]string{
        "X-Custom-Header": "value",
    },
})

fmt.Println(resp.Id)       // Message ID
fmt.Println(resp.Response) // Queue confirmation message

The SDK validates From, To, Subject and Html/Text locally and returns an error before making a request if any are missing. Response shape: SendEmailResponse{ Id string, Response string }.

`client.Batch.Send([]*SendEmailRequest)`

Send up to 100 emails in one request. Each element uses the same fields as a single send. Returns (*BatchSendResponse, error) with Summary (Total, Successful, Failed) and Results per message (each with Status, plus Id and Response on success or Error on failure).

resp, err := client.Batch.Send([]*jetemail.SendEmailRequest{
    {
        From:    "you@example.com",
        To:      []string{"alice@example.com"},
        Subject: "Hello Alice",
        Html:    "<p>Hi Alice!</p>",
    },
    {
        From:    "you@example.com",
        To:      []string{"bob@example.com"},
        Subject: "Hello Bob",
        Html:    "<p>Hi Bob!</p>",
    },
})
if err != nil {
    log.Fatal(err)
}

fmt.Println(resp.Summary.Successful)

for _, item := range resp.Results {
    if item.Status == "success" {
        fmt.Println(item.Id)
    } else {
        fmt.Println(item.Error)
    }
}

If an element fails local validation, Send returns a *jetemail.BatchValidationError (Index int, Err error) identifying which email is invalid, and nothing is sent.

Attachments

jetemail.Attachment has two fields: Filename and Data, where Data is the base64-encoded file content.

import (
    "encoding/base64"
    "os"
)

content, err := os.ReadFile("/path/to/invoice.pdf")
if err != nil {
    log.Fatal(err)
}

resp, err := client.Emails.Send(&jetemail.SendEmailRequest{
    From:    "you@example.com",
    To:      []string{"recipient@example.com"},
    Subject: "Invoice",
    Html:    "<p>Please find your invoice attached.</p>",
    Attachments: []jetemail.Attachment{
        {
            Filename: "invoice.pdf",
            Data:     base64.StdEncoding.EncodeToString(content),
        },
    },
})

Error handling

API errors (HTTP 4xx/5xx) are returned as *jetemail.APIError with StatusCode int, Message string and the raw Response []byte. Local validation failures and network/transport problems are returned as ordinary error values.

resp, err := client.Emails.Send(&jetemail.SendEmailRequest{...})
if err != nil {
    var apiErr *jetemail.APIError
    if errors.As(err, &apiErr) {
        // API returned an error
        fmt.Println(apiErr.StatusCode, apiErr.Message, string(apiErr.Response))
    } else {
        // Validation or transport error
        fmt.Println(err)
    }
}

Common status codes: 400 invalid request, 401 bad/missing API key, 500 server error.

Webhook signature verification

The SDK includes a helper for verifying webhook signatures. It checks the HMAC-SHA256 signature of the raw body and rejects events whose timestamp is outside the tolerance window (default jetemail.DefaultWebhookTolerance, 300 seconds).

import (
    "io"
    "net/http"

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

func webhookHandler(w http.ResponseWriter, r *http.Request) {
    body, err := io.ReadAll(r.Body)
    if err != nil {
        http.Error(w, "Bad request", http.StatusBadRequest)
        return
    }

    err = jetemail.VerifyWebhook(jetemail.VerifyWebhookParams{
        Signature: r.Header.Get("X-Webhook-Signature"),
        Timestamp: r.Header.Get("X-Webhook-Timestamp"),
        Body:      body,
        Secret:    "your-webhook-secret",
    })
    if err != nil {
        // Invalid or expired signature
        http.Error(w, "Invalid signature", http.StatusUnauthorized)
        return
    }

    // Signature is valid
    w.WriteHeader(http.StatusOK)
}

To use a different tolerance, call jetemail.VerifyWebhookWithTolerance(params, 10*time.Minute).

The helper compares the Signature value directly against the hex HMAC digest. If the header value you receive carries a sha256= prefix (see webhook security), strip it first, e.g. strings.TrimPrefix(r.Header.Get("X-Webhook-Signature"), "sha256=").

The package also exports jetemail.WebhookEvent (Type string, Timestamp int64, Data map[string]interface{}) for decoding the event payload, and constants for each event type (EventOutboundQueued, EventOutboundDelivered, EventOutboundBounced, EventOutboundRejected, EventOutboundDeferred, EventOutboundSpam, EventOutboundDropped, EventOutboundVirus, EventOutboundOpened, EventOutboundClicked, EventOutboundComplaint).

For additional examples, see the README on GitHub. REST details: API reference.

​Go SDK

​Installation

​Quick start

​Creating a client

​client.Emails.Send(*SendEmailRequest)

​client.Batch.Send([]*SendEmailRequest)

​Attachments

​Error handling

​Webhook signature verification

Go SDK

Installation

Quick start

Creating a client

`client.Emails.Send(*SendEmailRequest)`

`client.Batch.Send([]*SendEmailRequest)`

Attachments

Error handling

Webhook signature verification