Elastic Email Go SDK

The official Go client library for the Elastic Email REST API v4.

Installation • Quick start • Examples • API reference • Models • Contributing

• Transactional and bulk email. Send single messages, bulk campaigns or CSV merge-file sends.
• Contacts, lists and segments. Add, update, import, export and bulk-delete contacts.
• Campaigns and automations. Create, update, pause and trigger automations for a contact.
• Templates, files and attachments. Manage templates and uploaded files.
• Domains. Verify sending domains and check SPF, DKIM, tracking and certificate status.
• Safe retries. Pass an Idempotency-Key on email sends so a retried request is never sent or charged twice.
• Webhooks and inbound routes. Receive delivery events, optionally signed with HMAC-SHA256 and sent as JSON, and route incoming mail.
• Statistics, events and suppressions. Track delivery, bounces, complaints and unsubscribes.
• Subaccounts and security. Manage subaccounts and API keys.
• Idiomatic Go. Every call takes a context.Context, uses a fluent request builder ending in Execute(), and has no third-party runtime dependencies.

You'll also need an Elastic Email API key. You can create one in your API settings. Each endpoint's documentation lists the access level it needs.

Add the github.com/elasticemail/elasticemail-go/v4 module to your project:

go get github.com/elasticemail/elasticemail-go/v4@latest

Then import it. The package name is ElasticEmail:

import ElasticEmail "github.com/elasticemail/elasticemail-go/v4"

package main

import (
	"context"
	"os"

	ElasticEmail "github.com/elasticemail/elasticemail-go/v4"
)

func main() {
	client := ElasticEmail.NewAPIClient(ElasticEmail.NewConfiguration())

	ctx := context.WithValue(context.Background(), ElasticEmail.ContextAPIKeys,
		map[string]ElasticEmail.APIKey{
			"apikey": {Key: os.Getenv("ELASTICEMAIL_API_KEY")},
		})

	// use client and ctx, see below
}

The API key travels in the request context, so pass that ctx to every call.

html := ElasticEmail.NewBodyPart(ElasticEmail.BODYCONTENTTYPE_HTML)
html.SetContent("<h1>Hello!</h1><p>Thanks for signing up.</p>")
text := ElasticEmail.NewBodyPart(ElasticEmail.BODYCONTENTTYPE_PLAIN_TEXT)
text.SetContent("Hello! Thanks for signing up.")

content := ElasticEmail.NewEmailContent("My App <no-reply@yourdomain.com>")
content.SetSubject("Welcome aboard!")
content.SetBody([]ElasticEmail.BodyPart{*html, *text})

recipients := ElasticEmail.NewTransactionalRecipient([]string{"john.doe@example.com"})
message := ElasticEmail.NewEmailTransactionalMessageData(*recipients, *content)

result, httpRes, err := client.EmailsAPI.EmailsTransactionalPost(ctx).
	EmailTransactionalMessageData(*message).
	Execute()
if err != nil {
	var apiErr *ElasticEmail.GenericOpenAPIError
	if errors.As(err, &apiErr) && httpRes != nil {
		log.Fatalf("Elastic Email API error %d: %s", httpRes.StatusCode, apiErr.Body())
	}
	log.Fatal(err)
}
fmt.Printf("Sent. TransactionID: %s, MessageID: %s\n", result.GetTransactionID(), result.GetMessageID())

The from address must use a domain you've verified in your Elastic Email account.

Pass an idempotency key to make a send safe to retry after a timeout or a network error. If the first request already went through, the retry gets the stored response (same TransactionID and MessageID) with an Idempotency-Replayed: true header, and nothing is sent or charged twice.

key := uuid.NewString() // github.com/google/uuid: one new key per logical send

result, httpRes, err := client.EmailsAPI.EmailsTransactionalPost(ctx).
	EmailTransactionalMessageData(*message).
	IdempotencyKey(key).
	Execute()
if err != nil {
	// Timeout or 5xx: retry with the same key and the same message.
}
if httpRes != nil && httpRes.Header.Get("Idempotency-Replayed") == "true" {
	fmt.Println("Already sent earlier:", result.GetTransactionID())
}

Reuse a key only to retry the same send, with the same message, within 24 hours; EmailsPost and EmailsMergefilePost take IdempotencyKey too. The same key with a different message returns 422, a retry while the first request is still running returns 409, and 503 means the key couldn't be checked, so wait for Retry-After and retry with the same key. Without a key, sends behave exactly as before.

content := ElasticEmail.NewEmailContent("My App <no-reply@yourdomain.com>")
content.SetTemplateName("welcome-template")
content.SetMerge(map[string]string{"firstname": "John"})

recipients := ElasticEmail.NewTransactionalRecipient([]string{"john.doe@example.com"})
message := ElasticEmail.NewEmailTransactionalMessageData(*recipients, *content)

_, _, err := client.EmailsAPI.EmailsTransactionalPost(ctx).
	EmailTransactionalMessageData(*message).
	Execute()

Configuration.HTTPClient accepts any *http.Client, so you can set timeouts, a proxy or your own transport:

proxyURL, _ := url.Parse("http://myProxyUrl:80/")

cfg := ElasticEmail.NewConfiguration()
cfg.HTTPClient = &http.Client{
	Timeout:   30 * time.Second,
	Transport: &http.Transport{Proxy: http.ProxyURL(proxyURL)},
}
client := ElasticEmail.NewAPIClient(cfg)

The default client (http.DefaultClient) also honours the HTTP_PROXY and HTTPS_PROXY environment variables.

Optional model fields are pointers. Use the setters (SetSubject, SetMerge, …) or the Ptr* helpers (PtrString, PtrInt32, PtrBool, PtrTime, …) to build values inline, and the Get* accessors to read them without nil checks.

Webhooks can sign every request with HMAC-SHA256 and send events as a POST with a JSON body. Both options are set when you create the webhook and can't be changed later. Webhooks created without them keep working as unsigned GET requests.

payload := ElasticEmail.NewWebhookCreatePayload("my-webhook", "https://your-app.example.com/webhook")
payload.SetNotificationForSent(true)
payload.SetNotificationForOpened(true)
payload.SetNotificationForClicked(true)
payload.SetEnableSigning(true)
payload.SetDeliveryMethod(ElasticEmail.WEBHOOKDELIVERYMETHOD_POST_JSON)

created, _, err := client.WebhookAPI.WebhookPost(ctx).WebhookCreatePayload(*payload).Execute()
if err != nil {
	log.Fatal(err)
}
// Returned only now: store it, e.g. as ELASTICEMAIL_WEBHOOK_SECRET.
fmt.Println(created.GetSigningSecret())

SigningSecret is returned only when the webhook is created and when you rotate it with WebhookAPI.WebhookByPublicidSecretRotatePost, so store it right away. Each signed request carries X-ElasticEmail-Timestamp and X-ElasticEmail-Signature: v1=<hex>, where the signature is hex(HMAC-SHA256(secret, "{timestamp}\n{METHOD}\n{path and query}\n{raw body}")). Verify it against the raw body before you parse the JSON, reject timestamps more than 5 minutes old, and compare in constant time. The webhooks guide and the examples repository have ready-made handlers.

More complete, runnable samples are in the Elastic Email examples repository. It covers transactional email, SMTP, webhooks, inbound email, contacts and serverless platforms across 20+ languages and frameworks.

• 🐹 Go examples (plain net/http, Chi and Gin)
• 📂 All examples

Both are passed as entries in the map[string]ElasticEmail.APIKey stored under ElasticEmail.ContextAPIKeys, keyed by the scheme name.

• Up to 20 concurrent connections per account. The API doesn't return 429; a 5xx under load means slow down and retry with backoff
• A request with no response for about 50 seconds fails with a gateway error (5xx)
• Up to 50 recipients per POST /emails/transactional and 1000 contacts or suppressions per upload (413 above that). For more recipients, send one bulk POST /emails

All URIs are relative to https://api.elasticemail.com/v4. The SDK covers 115 endpoints across 16 API services, exposed as fields on APIClient: CampaignsAPI, ContactsAPI, DomainsAPI, EmailsAPI, EventsAPI, FilesAPI, InboundRouteAPI, ListsAPI, SecurityAPI, SegmentsAPI, StatisticsAPI, SubAccountsAPI, SuppressionsAPI, TemplatesAPI, VerificationsAPI and WebhookAPI.

The SDK follows the Elastic Email API v4 and uses semantic import versioning, so the major version is part of the module path (/v4). Available versions are listed on pkg.go.dev and in GitHub Releases.

Contributions are welcome! Most of this SDK is generated from the OpenAPI specification, so please read CONTRIBUTING.md before opening a pull request.

• 🐛 Report a bug
• 💡 Request a feature
• 🔒 Report a security issue

This project follows the Contributor Covenant Code of Conduct.

• 💬 Chat with support on elasticemail.com (preferred)
• 📚 API documentation
• 🧪 Examples repository
• 🐛 GitHub issues, for bugs in this SDK only

Released under the MIT License. Copyright © 2021–2026 Elastic Email.