We're glad you're here.
"), TextContent: ahasend.String("Welcome aboard! We're glad you're here."), } digest := sha256.Sum256([]byte(in.SignupID)) idempotencyKey := "welcome-" + hex.EncodeToString(digest[:]) ctx, cancel := context.WithTimeout(c.Request.Context(), 25*time.Second) defer cancel() response, _, err := ahasendClient.MessagesAPI.CreateMessage( ctx, accountID, message, api.WithIdempotencyKey(idempotencyKey), ) if err != nil { var apiErr *api.APIError if errors.As(err, &apiErr) { log.Printf( "AhaSend request failed status=%d type=%s request_id=%s", apiErr.StatusCode, apiErr.Type, apiErr.RequestID, ) switch apiErr.Type { case api.ErrorTypeIdempotency: // This key was already used with a different payload. Retrying // can never succeed, so do not answer with a 5xx. c.JSON(http.StatusConflict, gin.H{"error": "idempotency key reused with a different payload"}) return case api.ErrorTypeIdempotencyConflict: // An earlier send with this key is still running upstream. c.Header("Retry-After", strconv.Itoa(apiErr.RetryAfter)) c.JSON(http.StatusServiceUnavailable, gin.H{"error": "send already in progress"}) return case api.ErrorTypeValidation, api.ErrorTypeAuthentication, api.ErrorTypePermission, api.ErrorTypeNotFound: // A rejected message, a revoked key, or a missing scope is a // deployment fault: every retry fails identically. Alert on // this rather than inviting callers to hammer it. c.JSON(http.StatusInternalServerError, gin.H{"error": "email service is misconfigured"}) return case api.ErrorTypeRateLimit: // The SDK already backed off and retried. Hand the remaining // wait to the caller instead of hiding it behind a bare 502. if apiErr.RetryAfter > 0 { c.Header("Retry-After", strconv.Itoa(apiErr.RetryAfter)) } c.JSON(http.StatusServiceUnavailable, gin.H{"error": "send rate limited"}) return } } else { log.Print("AhaSend request failed") } c.JSON(http.StatusBadGateway, gin.H{"error": "failed to send email"}) return } if response == nil || len(response.Data) != 1 { log.Print("AhaSend returned an unexpected result count") c.JSON(http.StatusBadGateway, gin.H{"error": "unexpected email result"}) return } result := response.Data[0] if result.Status == "error" { log.Print("AhaSend rejected 1 recipient") c.JSON(http.StatusUnprocessableEntity, gin.H{"error": "recipient rejected"}) return } c.JSON(http.StatusAccepted, gin.H{"status": result.Status, "message_id": result.ID}) } ``` The send API is multi-status: a `202` carries one `Data` entry per recipient, and an entry can report `Status == "error"` with a nil `ID` even though the SDK call itself returned no error. This handler sends to one recipient and checks the single entry it expects; loop over every entry once you extend `Recipients`. Split the failures the same way the handler does: a rejected payload, a revoked key, or a missing scope fails identically on every attempt, so surface it as a `500` and page someone, while a rate limit or an upstream `5xx` is worth retrying — the rate-limit branch passes AhaSend's own `Retry-After` back to the caller. The SDK automatically retries transient failures and attaches an automatic idempotency key to each send. This handler overrides it with a stable key derived from the immutable signup ID so a later retry of the same business operation can reuse the key. Reuse a key only with the exact same payload: the API rejects the same key carrying a changed body with `422`, which the SDK reports as `ErrorTypeIdempotency` and the handler turns into a `409` rather than a retryable `502`. A `409` from the API is the separate in-progress case — an earlier request with that key has not finished — which the SDK reports as `ErrorTypeIdempotencyConflict` with the remaining seconds in `RetryAfter`. Stored outcomes replay for 24 hours, but a 5xx is not stored, so a retry after a server error can still send twice; persist workflow state and make uncertain results safe to reconcile. ## Handle Webhooks Gin handlers wrap a standard `*http.Request`, so the SDK's `ParseRequest` works directly: it verifies the HMAC signature and timestamp, then returns a typed event. Timestamp validation is not replay deduplication. No body-parsing middleware may run on this route first. ```go webhook.go theme={null} package main import ( "errors" "net/http" "github.com/AhaSend/ahasend-go/webhooks" "github.com/gin-gonic/gin" ) var verifier *webhooks.WebhookVerifier const maxWebhookBodyBytes int64 = 1 << 20 func handleAhaSendWebhook(c *gin.Context) { c.Request.Body = http.MaxBytesReader(c.Writer, c.Request.Body, maxWebhookBodyBytes) _, err := verifier.ParseRequest(c.Request) if err != nil { var tooLarge *http.MaxBytesError switch { case errors.As(err, &tooLarge): c.Status(http.StatusRequestEntityTooLarge) case errors.Is(err, webhooks.ErrUnknownEventType): // ParseRequest verifies the signature before classifying the event. c.Status(http.StatusNoContent) default: c.Status(http.StatusBadRequest) } return } // This minimal receiver has no business side effect. c.Status(http.StatusNoContent) } ``` Create the webhook in your [AhaSend dashboard](https://dash.ahasend.com) pointing at `https://your-app.com/webhooks/ahasend`, and copy its secret into `AHASEND_WEBHOOK_SECRET` exactly as shown (including the `aha-whsec-` prefix). This minimal receiver deliberately verifies and acknowledges without performing a business side effect. Before adding one, atomically commit the verified `webhook-id` header together with durable queue/outbox work; acknowledge an already-committed ID with 2xx, and process durable work idempotently. Do not launch a bare goroutine: it can be lost when the process exits, and `*gin.Context` is recycled once the handler returns, so anything that outlives the request must carry `c.Copy()` instead of `c`. Keep reverse-proxy request-size and concurrency limits at least as strict as the application limit above, return promptly, and keep failures opaque. ## Going Further * **Templating**: set `Substitutions: map[string]interface{}{"first_name": "Jane"}` and use `{{ first_name }}` in the subject or body. * **Batch sends**: `Recipients` accepts up to 100 entries; each gets a separate message. * **Tags**: set `Tags: []string{"welcome"}` to filter messages in list and statistics queries. Webhooks are scoped by domain, not by tag, and message events do not carry the tags. * **Rate limits**: when sending at volume, tune `SetSendMessageRateLimit(requestsPerSecond, burstCapacity)` to stay within your account's limits. * **Other frameworks**: the same SDK patterns work in [chi](/docs/guides/chi), [Echo](/docs/guides/echo), and [Fiber](/docs/guides/fiber). * **Attachments**: add `Attachments` with `Data`, `ContentType`, `ContentDisposition: "attachment"`, and `FileName`. Set `Base64: true` for binary files such as PDFs. See the [API reference](/docs/api-reference) for every service the SDK exposes (`DomainsAPI`, `SuppressionsAPI`, `StatisticsAPI`, and more). ## Troubleshooting