/api/v1/transactional-emails (#7)

Author: notnmeyer

README.md

@@ -55,7 +55,7 @@ client := loops.NewClient("YOUR_API_KEY",
 - Contact properties — `ListContactProperties`, `CreateContactProperty`
 - Mailing lists — `ListMailingLists`
 - Events — `SendEvent`
-- Transactional — `SendTransactional`, `ListTransactional`
+- Transactional — `SendTransactional`, `ListTransactionals`, `CreateTransactional`, `GetTransactional`, `UpdateTransactional`, `EnsureTransactionalDraft`, `PublishTransactional`
 - Email messages — `GetEmailMessage`, `UpdateEmailMessage`
 - Campaigns — `CreateCampaign`, `UpdateCampaign`, `GetCampaign`, `ListCampaigns`
 - Components — `GetComponent`, `ListComponents`
@@ -88,10 +88,10 @@ Requests are automatically retried with exponential backoff and jitter on `429`
 
 ## Pagination
 
-`ListTransactional` and `ListCampaigns` return a single page of results along with a `*Pagination` value. Pass a `PaginationParams` to control page size and cursor:
+`ListTransactionals` and `ListCampaigns` return a single page of results along with a `*Pagination` value. Pass a `PaginationParams` to control page size and cursor:
 
 ```go
-items, page, err := client.ListTransactional(loops.PaginationParams{PerPage: "50"})
+items, page, err := client.ListTransactionals(loops.PaginationParams{PerPage: "50"})
 if err != nil {
     log.Fatal(err)
 }
@@ -101,8 +101,8 @@ if err != nil {
 To fetch every page, use the generic `Paginate` helper:
 
 ```go
-all, err := loops.Paginate(func(cursor string) ([]loops.TransactionalEmail, *loops.Pagination, error) {
-    return client.ListTransactional(loops.PaginationParams{Cursor: cursor})
+all, err := loops.Paginate(func(cursor string) ([]loops.Transactional, *loops.Pagination, error) {
+    return client.ListTransactionals(loops.PaginationParams{Cursor: cursor})
 })
 ```
 

transactional.go

@@ -77,6 +77,10 @@ func (c *Client) SendTransactional(req SendTransactionalRequest) error {
 //	all, err := loops.Paginate(func(cursor string) ([]loops.TransactionalEmail, *loops.Pagination, error) {
 //	    return client.ListTransactional(loops.PaginationParams{Cursor: cursor})
 //	})
+//
+// Deprecated: use [Client.ListTransactionals], which returns the richer
+// [Transactional] shape (draft and published email message IDs, separate
+// created/updated timestamps).
 func (c *Client) ListTransactional(params PaginationParams) ([]TransactionalEmail, *Pagination, error) {
 	q := url.Values{}
 	if params.PerPage != "" {

transactional_emails.go

@@ -0,0 +1,228 @@
+package loops
+
+import (
+	"bytes"
+	"encoding/json"
+	"fmt"
+	"net/http"
+	"net/url"
+)
+
+// Transactional describes a transactional email template managed via the
+// content API. A transactional email can have a draft and/or a published
+// [EmailMessage], linked via DraftEmailMessageID and PublishedEmailMessageID.
+type Transactional struct {
+	ID                      string   `json:"id"`
+	Name                    string   `json:"name"`
+	DraftEmailMessageID     *string  `json:"draftEmailMessageId"`
+	PublishedEmailMessageID *string  `json:"publishedEmailMessageId"`
+	CreatedAt               string   `json:"createdAt"`
+	UpdatedAt               string   `json:"updatedAt"`
+	DataVariables           []string `json:"dataVariables"`
+}
+
+// TransactionalDraft is returned by [Client.CreateTransactional] and
+// [Client.EnsureTransactionalDraft]. It embeds the [Transactional] and adds
+// DraftEmailMessageContentRevisionID, which should be passed as
+// ExpectedRevisionID on the first call to [Client.UpdateEmailMessage] for
+// optimistic concurrency control.
+type TransactionalDraft struct {
+	Transactional
+	DraftEmailMessageContentRevisionID *string `json:"draftEmailMessageContentRevisionId"`
+}
+
+// CreateTransactionalRequest is the request body for [Client.CreateTransactional].
+type CreateTransactionalRequest struct {
+	Name string `json:"name"`
+}
+
+// UpdateTransactionalRequest is the request body for [Client.UpdateTransactional].
+type UpdateTransactionalRequest struct {
+	Name string `json:"name"`
+}
+
+// CreateTransactional creates a new transactional email with an empty draft
+// email message. Use [Client.UpdateEmailMessage] on the returned
+// DraftEmailMessageID to set the subject, sender, and LMX content, then call
+// [Client.PublishTransactional] to publish.
+func (c *Client) CreateTransactional(req CreateTransactionalRequest) (*TransactionalDraft, error) {
+	b, err := json.Marshal(req)
+	if err != nil {
+		return nil, fmt.Errorf("failed to encode request: %w", err)
+	}
+
+	httpReq, err := c.newRequest(http.MethodPost, "/transactional-emails", bytes.NewReader(b))
+	if err != nil {
+		return nil, err
+	}
+
+	resp, err := c.do(httpReq)
+	if err != nil {
+		return nil, err
+	}
+	defer resp.Body.Close()
+
+	if resp.StatusCode != http.StatusCreated {
+		return nil, errorFromResponse(resp)
+	}
+
+	var result TransactionalDraft
+	if err := json.NewDecoder(resp.Body).Decode(&result); err != nil {
+		return nil, fmt.Errorf("failed to decode response: %w", err)
+	}
+
+	return &result, nil
+}
+
+// GetTransactional returns the transactional email identified by id.
+func (c *Client) GetTransactional(id string) (*Transactional, error) {
+	req, err := c.newRequest(http.MethodGet, "/transactional-emails/"+id, nil)
+	if err != nil {
+		return nil, err
+	}
+
+	resp, err := c.do(req)
+	if err != nil {
+		return nil, err
+	}
+	defer resp.Body.Close()
+
+	if resp.StatusCode != http.StatusOK {
+		return nil, errorFromResponse(resp)
+	}
+
+	var result Transactional
+	if err := json.NewDecoder(resp.Body).Decode(&result); err != nil {
+		return nil, fmt.Errorf("failed to decode response: %w", err)
+	}
+
+	return &result, nil
+}
+
+// UpdateTransactional updates the transactional email identified by id and
+// returns its new state.
+func (c *Client) UpdateTransactional(id string, req UpdateTransactionalRequest) (*Transactional, error) {
+	b, err := json.Marshal(req)
+	if err != nil {
+		return nil, fmt.Errorf("failed to encode request: %w", err)
+	}
+
+	httpReq, err := c.newRequest(http.MethodPost, "/transactional-emails/"+id, bytes.NewReader(b))
+	if err != nil {
+		return nil, err
+	}
+
+	resp, err := c.do(httpReq)
+	if err != nil {
+		return nil, err
+	}
+	defer resp.Body.Close()
+
+	if resp.StatusCode != http.StatusOK {
+		return nil, errorFromResponse(resp)
+	}
+
+	var result Transactional
+	if err := json.NewDecoder(resp.Body).Decode(&result); err != nil {
+		return nil, fmt.Errorf("failed to decode response: %w", err)
+	}
+
+	return &result, nil
+}
+
+// EnsureTransactionalDraft ensures the transactional email has a draft email
+// message. If a draft already exists it is returned unchanged; otherwise a
+// new empty draft is created (seeded from the most recent published version
+// when present).
+func (c *Client) EnsureTransactionalDraft(id string) (*TransactionalDraft, error) {
+	req, err := c.newRequest(http.MethodPost, "/transactional-emails/"+id+"/draft", nil)
+	if err != nil {
+		return nil, err
+	}
+
+	resp, err := c.do(req)
+	if err != nil {
+		return nil, err
+	}
+	defer resp.Body.Close()
+
+	if resp.StatusCode != http.StatusOK {
+		return nil, errorFromResponse(resp)
+	}
+
+	var result TransactionalDraft
+	if err := json.NewDecoder(resp.Body).Decode(&result); err != nil {
+		return nil, fmt.Errorf("failed to decode response: %w", err)
+	}
+
+	return &result, nil
+}
+
+// PublishTransactional publishes the transactional email's current draft
+// email message. The draft becomes the published version and the draft is
+// cleared.
+func (c *Client) PublishTransactional(id string) (*Transactional, error) {
+	req, err := c.newRequest(http.MethodPost, "/transactional-emails/"+id+"/publish", nil)
+	if err != nil {
+		return nil, err
+	}
+
+	resp, err := c.do(req)
+	if err != nil {
+		return nil, err
+	}
+	defer resp.Body.Close()
+
+	if resp.StatusCode != http.StatusOK {
+		return nil, errorFromResponse(resp)
+	}
+
+	var result Transactional
+	if err := json.NewDecoder(resp.Body).Decode(&result); err != nil {
+		return nil, fmt.Errorf("failed to decode response: %w", err)
+	}
+
+	return &result, nil
+}
+
+// ListTransactionals returns a single page of transactional emails along
+// with pagination information. To iterate every page, use [Paginate].
+func (c *Client) ListTransactionals(params PaginationParams) ([]Transactional, *Pagination, error) {
+	q := url.Values{}
+	if params.PerPage != "" {
+		q.Set("perPage", params.PerPage)
+	}
+	if params.Cursor != "" {
+		q.Set("cursor", params.Cursor)
+	}
+
+	path := "/transactional-emails"
+	if len(q) > 0 {
+		path += "?" + q.Encode()
+	}
+
+	req, err := c.newRequest(http.MethodGet, path, nil)
+	if err != nil {
+		return nil, nil, err
+	}
+
+	resp, err := c.do(req)
+	if err != nil {
+		return nil, nil, err
+	}
+	defer resp.Body.Close()
+
+	if resp.StatusCode != http.StatusOK {
+		return nil, nil, errorFromResponse(resp)
+	}
+
+	var result struct {
+		Pagination Pagination      `json:"pagination"`
+		Data       []Transactional `json:"data"`
+	}
+	if err := json.NewDecoder(resp.Body).Decode(&result); err != nil {
+		return nil, nil, fmt.Errorf("failed to decode response: %w", err)
+	}
+
+	return result.Data, &result.Pagination, nil
+}