add client.GetSuppressions

See https://postmarkapp.com/developer/api/suppressions-api

Credit to Bochao Wang (@plutowang) for their original pull request:

keighl#31

suppressions.go

@@ -0,0 +1,89 @@
+package postmark
+
+import (
+	"context"
+	"fmt"
+	"net/url"
+	"time"
+)
+
+// SuppressionReasonType - The reason type of suppression
+type SuppressionReasonType string
+
+// OriginType - The reason type of origin
+type OriginType string
+
+const (
+	// HardBounceReason means an email sent to the address returned a hard bounce.
+	HardBounceReason SuppressionReasonType = "HardBounce"
+
+	// SpamComplaintReason means the recipient marked an email as spam.
+	SpamComplaintReason SuppressionReasonType = "SpamComplaint"
+
+	// ManualSuppressionReason means the recipient followed an unsubscribe link.
+	ManualSuppressionReason SuppressionReasonType = "ManualSuppression"
+
+	// RecipientOrigin means the email was added to the suppression list
+	// as a result of the recipient's own action, e.g. by following an unsubscribe link.
+	RecipientOrigin OriginType = "Recipient"
+
+	// CustomerOrigin means the email was added to the suppression list as
+	// the result of action by the Postmark account holder (e.g. Postmark's
+	// customer).
+	CustomerOrigin OriginType = "Customer"
+
+	// AdminOrigin means the email was added to the suppression list as
+	// the result of action by Postmark staff.
+	AdminOrigin OriginType = "Admin"
+)
+
+// Suppression contains a suppressed email address for a particular message stream.
+type Suppression struct {
+	// EmailAddress is the address that is suppressed (can't be emailed any more)
+	EmailAddress string
+
+	// SuppressionReason is why the email address was added to the suppression list.
+	// Possible options: HardBounce, SpamComplaint, ManualSuppression
+	SuppressionReason SuppressionReasonType
+
+	// Origin describes who added the email address to the suppression list.
+	// Possible options: Recipient, Customer, Admin.
+	Origin OriginType
+
+	// CreatedAt is when the email address was added to the suppression list.
+	CreatedAt time.Time
+}
+
+// suppressionsResponse - A message received from the Postmark server
+type suppressionsResponse struct {
+	// Suppressions - The slice of suppression email address.
+	Suppressions []Suppression
+}
+
+// GetSuppressions fetches email addresses in the list of suppression dump on the server
+// It returns a Suppressions slice, and any error that occurred
+// https://postmarkapp.com/developer/api/suppressions-api#suppression-dump
+func (client *Client) GetSuppressions(
+	ctx context.Context,
+	streamID string,
+	options map[string]interface{},
+) ([]Suppression, error) {
+
+	values := &url.Values{}
+	for k, v := range options {
+		values.Add(k, fmt.Sprintf("%v", v))
+	}
+
+	path := fmt.Sprintf("message-streams/%s/suppressions/dump", streamID)
+	if len(options) != 0 {
+		path = fmt.Sprintf("%s?%s", path, values.Encode())
+	}
+
+	res := suppressionsResponse{}
+	err := client.doRequest(ctx, parameters{
+		Method:    "GET",
+		Path:      path,
+		TokenType: serverToken,
+	}, &res)
+	return res.Suppressions, err
+}

suppressions_test.go

@@ -0,0 +1,84 @@
+package postmark
+
+import (
+	"context"
+	"net/http"
+	"testing"
+
+	"goji.io/pat"
+)
+
+func TestGetSuppressions(t *testing.T) {
+	responseJSON := `{
+		"Suppressions":[
+		  {
+			"EmailAddress":"[email protected]",
+			"SuppressionReason":"ManualSuppression",
+			"Origin": "Recipient",
+			"CreatedAt":"2019-12-10T08:58:33-05:00"
+		  },
+		  {
+			"EmailAddress":"[email protected]",
+			"SuppressionReason":"HardBounce",
+			"Origin": "Recipient",
+			"CreatedAt":"2019-12-11T08:58:33-05:00"
+		  },
+		  {
+			"EmailAddress":"[email protected]",
+			"SuppressionReason":"SpamComplaint",
+			"Origin": "Recipient",
+			"CreatedAt":"2019-12-12T08:58:33-05:00"
+		  }
+		]
+	  }`
+
+	tMux.HandleFunc(pat.Get("/message-streams/:StreamID/suppressions/dump"), func(w http.ResponseWriter, req *http.Request) {
+		w.Write([]byte(responseJSON))
+	})
+
+	res, err := client.GetSuppressions(context.Background(), "outbound", nil)
+
+	if err != nil {
+		t.Fatalf("GetSuppressions: %s", err.Error())
+	}
+
+	if len(res) != 3 {
+		t.Fatalf("GetSuppressions: wrong number of suppression (%d)", len(res))
+	}
+
+	if res[0].EmailAddress != "[email protected]" {
+		t.Fatalf("GetSuppressions: wrong suppression email address: %s", res[0].EmailAddress)
+	}
+
+	responseJSON = `{
+		"Suppressions":[
+		  {
+			"EmailAddress":"[email protected]",
+			"SuppressionReason":"ManualSuppression",
+			"Origin": "Recipient",
+			"CreatedAt":"2019-12-10T08:58:33-05:00"
+		  }
+		]
+	  }`
+
+	tMux.HandleFunc(pat.Get("/message-streams/:StreamID/suppressions/dump"), func(w http.ResponseWriter, req *http.Request) {
+		w.Write([]byte(responseJSON))
+	})
+
+	res, err = client.GetSuppressions(context.Background(), "outbound", map[string]interface{}{
+		"emailaddress":      "[email protected]",
+		"fromdate":          "2019-12-10",
+		"todate":            "2019-12-11",
+		"suppressionreason": HardBounceReason,
+		"origin":            RecipientOrigin,
+	})
+
+	if len(res) != 1 {
+		t.Fatalf("GetSuppressions: wrong number of suppression (%d)", len(res))
+	}
+
+	if res[0].EmailAddress != "[email protected]" {
+		t.Fatalf("GetSuppressions: wrong suppression email address: %s", res[0].EmailAddress)
+	}
+
+}