Skip to main content
SDKs · Go

Go SDK

Go 1.24+, context on every call and iterators for pagination.

v0.1.0pkg.go.devGitHub70 methods(*T, error)

Installation

Add the package to your project.

terminal
go get github.com/Coffee-Mail/coffee-mail-sdk-go

Configure the client

The key comes from COFFEEMAIL_API_KEY or the constructor. Use one key per environment.

client
import coffeemail "github.com/Coffee-Mail/coffee-mail-sdk-go" client, err := coffeemail.NewClient("") // vazio: lê COFFEEMAIL_API_KEYif err != nil {	log.Fatal(err)}

Send an email

The send is queued and returns within milliseconds with the id and the queued status. Returns: (*T, error).

Methods return (*T, error), the Go idiom: check err before using the value. API errors are *coffeemail.Error and work with errors.Is (ErrNotFound, ErrRateLimited…).
send
sent, err := client.Emails.Send(ctx, &coffeemail.SendEmailParams{	From:    coffeemail.Address{Email: "pedidos@acme.com.br", Name: "Acme"},	To:      []coffeemail.Address{{Email: "ana@exemplo.com.br"}},	Subject: "Seu pedido #4821 foi enviado",	HTML:    "<p>Chega amanhã.</p>",})if err != nil {	return err}log.Println(sent.ID, sent.Status)

Handle errors

API errors arrive typed, with code, status and requestId; nothing is thrown on the common path.

errors
_, err := client.Domains.Get(ctx, id)if errors.Is(err, coffeemail.ErrNotFound) {	return nil} var apiErr *coffeemail.Errorif errors.As(err, &apiErr) {	log.Printf("status=%d code=%s requestId=%s", apiErr.Status, apiErr.Code, apiErr.RequestID)}

Paginate

Lists return the page and a nextCursor; pass it as after to fetch the next one.

paginate
for email, err := range client.Emails.ListAll(ctx, &coffeemail.ListEmailsParams{}) {	if err != nil {		return err	}	handle(email)}

Verify webhooks

Validate x-webhook-signature against the raw request body, x-webhook-timestamp and x-webhook-idempotency-key. The default window is 300 seconds.

The webhook subpackage verifies the signature. To check by hand: sha256= + hex HMAC-SHA256 of "timestamp.idempotencyKey.body" with the whsec_ secret, compared in constant time.
webhook
import "github.com/Coffee-Mail/coffee-mail-sdk-go/webhook" event, err := webhook.ParseRequest(r, os.Getenv("COFFEEMAIL_WEBHOOK_SECRET"))if err != nil {	http.Error(w, "assinatura inválida", http.StatusUnauthorized)	return}

Method reference

Every public method, grouped by resource. Each row shows the endpoint it calls; open the API reference for fields and responses.

Emails8 methods

Endpoints →
MethodEndpoint called
client.Emails.Send(ctx, …)POST/emails
client.Emails.SendBatch(ctx, …)POST/emails/batch
client.Emails.Get(ctx, …)GET/emails/{id}
client.Emails.List(ctx, …)GET/emails
client.Emails.GetEvents(ctx, …)GET/emails/{id}/events
client.Emails.GetTags(ctx, …)GET/emails/tags
client.Emails.Cancel(ctx, …)POST/emails/{id}/cancel
client.Emails.Resend(ctx, …)POST/emails/{id}/resend

Domains10 methods

Endpoints →
MethodEndpoint called
client.Domains.Create(ctx, …)POST/domains
client.Domains.List(ctx, …)GET/domains
client.Domains.Get(ctx, …)GET/domains/{id}
client.Domains.Verify(ctx, …)POST/domains/{id}/verify
client.Domains.Delete(ctx, …)DELETE/domains/{id}
client.Domains.GetHealth(ctx, …)POST/domains/{id}/health
client.Domains.GetWarmupStatus(ctx, …)GET/domains/{id}/warmup
client.Domains.RotateDKIM(ctx, …)POST/domains/{id}/dkim/rotate
client.Domains.SetTrackingDomain(ctx, …)PUT/domains/{id}/tracking-domain
client.Domains.RemoveTrackingDomain(ctx, …)DELETE/domains/{id}/tracking-domain

Templates12 methods

Endpoints →
MethodEndpoint called
client.Templates.Create(ctx, …)POST/templates
client.Templates.List(ctx, …)GET/templates
client.Templates.Get(ctx, …)GET/templates/{id}
client.Templates.Update(ctx, …)PATCH/templates/{id}
client.Templates.Delete(ctx, …)DELETE/templates/{id}
client.Templates.Preview(ctx, …)POST/templates/preview
client.Templates.Format(ctx, …)POST/templates/format
client.Templates.TestRender(ctx, …)POST/templates/test-render
client.Templates.TestSend(ctx, …)POST/templates/{id}/test-send
client.Templates.ListVersions(ctx, …)GET/templates/{id}/versions
client.Templates.GetVersion(ctx, …)GET/templates/{id}/versions/{version}
client.Templates.RestoreVersion(ctx, …)POST/templates/{id}/versions/{version}/restore

Audiences and contacts10 methods

Endpoints →
MethodEndpoint called
client.Audiences.Create(ctx, …)POST/audiences
client.Audiences.List(ctx, …)GET/audiences
client.Audiences.Get(ctx, …)GET/audiences/{id}
client.Audiences.Update(ctx, …)PUT/audiences/{id}
client.Audiences.Delete(ctx, …)DELETE/audiences/{id}
client.Audiences.Contacts.Create(ctx, …)POST/audiences/{id}/contacts
client.Audiences.Contacts.List(ctx, …)GET/audiences/{id}/contacts
client.Audiences.Contacts.BulkAdd(ctx, …)POST/audiences/{id}/contacts/bulk
client.Audiences.Contacts.Update(ctx, …)PUT/audiences/{id}/contacts/{contactId}
client.Audiences.Contacts.Delete(ctx, …)DELETE/audiences/{id}/contacts/{contactId}

Campaigns6 methods

Endpoints →
MethodEndpoint called
client.Broadcasts.Create(ctx, …)POST/broadcasts
client.Broadcasts.List(ctx, …)GET/broadcasts
client.Broadcasts.Get(ctx, …)GET/broadcasts/{id}
client.Broadcasts.Send(ctx, …)POST/broadcasts/{id}/send
client.Broadcasts.TestSend(ctx, …)POST/broadcasts/{id}/test-send
client.Broadcasts.Cancel(ctx, …)POST/broadcasts/{id}/cancel

Senders5 methods

Endpoints →
MethodEndpoint called
client.Senders.Create(ctx, …)POST/senders
client.Senders.List(ctx, …)GET/senders
client.Senders.Verify(ctx, …)POST/senders/verify
client.Senders.ResendVerification(ctx, …)POST/senders/{id}/resend-verification
client.Senders.Delete(ctx, …)DELETE/senders/{id}

Suppressions6 methods

Endpoints →
MethodEndpoint called
client.Suppressions.Create(ctx, …)POST/suppressions
client.Suppressions.List(ctx, …)GET/suppressions
client.Suppressions.Get(ctx, …)GET/suppressions/{id}
client.Suppressions.Delete(ctx, …)DELETE/suppressions/{id}
client.Suppressions.Reactivate(ctx, …)POST/suppressions/{id}/reactivate
client.Suppressions.BulkCreate(ctx, …)POST/suppressions/bulk

Webhooks11 methods

Endpoints →
MethodEndpoint called
client.Webhooks.Create(ctx, …)POST/webhooks
client.Webhooks.List(ctx, …)GET/webhooks
client.Webhooks.Get(ctx, …)GET/webhooks/{id}
client.Webhooks.Update(ctx, …)PUT/webhooks/{id}
client.Webhooks.Toggle(ctx, …)PATCH/webhooks/{id}
client.Webhooks.Delete(ctx, …)DELETE/webhooks/{id}
client.Webhooks.RotateSecret(ctx, …)POST/webhooks/{id}/rotate-secret
client.Webhooks.ListDeliveries(ctx, …)GET/webhooks/{id}/deliveries
client.Webhooks.Test(ctx, …)POST/webhooks/{id}/test
client.Webhooks.GetDelivery(ctx, …)GET/webhooks/{id}/deliveries/{deliveryId}
client.Webhooks.ReplayDelivery(ctx, …)POST/webhooks/{id}/deliveries/{deliveryId}/replay

Statistics1 method

Endpoints →
MethodEndpoint called
client.Stats.Get(ctx, …)GET/stats

Validation1 method

Endpoints →
MethodEndpoint called
client.Validation.Validate(ctx, …)POST/validate