Repository: mailgun/mailgun-go
Pull request #416 (2025-05-15 17:53:39)

DE-1534 Deprecate /v3/domains/{name}/connection and fix web_prefix update


Patch:
diff --git a/domains.go b/domains.go
index 896f709..27d5abc 100644
--- a/domains.go
+++ b/domains.go
@@ -175,7 +175,9 @@ func (mg *Client) GetDomain(ctx context.Context, domain string, _ *GetDomainOpti
 	return resp, err
 }
 
-func (mg *Client) VerifyAndReturnDomain(ctx context.Context, domain string) (mtypes.GetDomainResponse, error) {
+// VerifyDomain verifies the domains DNS records (includes A, CNAME, SPF,
+// DKIM and MX records) to ensure the domain is ready and able to send.
+func (mg *Client) VerifyDomain(ctx context.Context, domain string) (mtypes.GetDomainResponse, error) {
 	r := newHTTPRequest(generateApiUrl(mg, 4, domainsEndpoint) + "/" + domain + "/verify")
 	r.setClient(mg.HTTPClient())
 	r.setBasicAuth(basicAuthUser, mg.APIKey())
@@ -186,6 +188,14 @@ func (mg *Client) VerifyAndReturnDomain(ctx context.Context, domain string) (mty
 	return resp, err
 }
 
+// VerifyAndReturnDomain verifies the domains DNS records (includes A, CNAME, SPF,
+// DKIM and MX records) to ensure the domain is ready and able to send.
+// Deprecated: use VerifyDomain instead.
+// TODO(v6): remove this method
+func (mg *Client) VerifyAndReturnDomain(ctx context.Context, domain string) (mtypes.GetDomainResponse, error) {
+	return mg.VerifyDomain(ctx, domain)
+}
+
 // CreateDomainOptions - optional parameters when creating a domain
 // https://documentation.mailgun.com/docs/mailgun/api-reference/openapi-final/tag/Domains/#tag/Domains/operation/POST-v4-domains
 // TODO(vtopc): support all fields
@@ -205,13 +215,13 @@ type CreateDomainOptions struct {
 // The spamAction domain must be one of Delete, Tag, or Disabled.
 // The wildcard parameter instructs Mailgun to treat all subdomains of this domain uniformly if true,
 // and as different domains if false.
-func (mg *Client) CreateDomain(ctx context.Context, name string, opts *CreateDomainOptions) (mtypes.GetDomainResponse, error) {
+func (mg *Client) CreateDomain(ctx context.Context, domain string, opts *CreateDomainOptions) (mtypes.GetDomainResponse, error) {
 	r := newHTTPRequest(generateApiUrl(mg, 4, domainsEndpoint))
 	r.setClient(mg.HTTPClient())
 	r.setBasicAuth(basicAuthUser, mg.APIKey())
 
 	payload := newUrlEncodedPayload()
-	payload.addValue("name", name)
+	payload.addValue("name", domain)
 
 	if opts != nil {
 		if opts.SpamAction != "" {
@@ -242,8 +252,8 @@ func (mg *Client) CreateDomain(ctx context.Context, name string, opts *CreateDom
 }
 
 // DeleteDomain instructs Mailgun to dispose of the named domain name
-func (mg *Client) DeleteDomain(ctx context.Context, name string) error {
-	r := newHTTPRequest(generateApiUrl(mg, 3, domainsEndpoint) + "/" + name)
+func (mg *Client) DeleteDomain(ctx context.Context, domain string) error {
+	r := newHTTPRequest(generateApiUrl(mg, 3, domainsEndpoint) + "/" + domain)
 	r.setClient(mg.HTTPClient())
 	r.setBasicAuth(basicAuthUser, mg.APIKey())
 	_, err := makeDeleteRequest(ctx, r)
@@ -252,14 +262,15 @@ func (mg *Client) DeleteDomain(ctx context.Context, name string) error {
 
 // UpdateDomainOptions options for updating a domain
 type UpdateDomainOptions struct {
-	WebScheme string
-	WebPrefix string
+	WebScheme        string
+	WebPrefix        string
+	RequireTLS       *bool
+	SkipVerification *bool
 }
 
 // UpdateDomain updates a domain's attributes.
-// Currently only the web_scheme update is supported, spam_action and wildcard are to be added.
-func (mg *Client) UpdateDomain(ctx context.Context, name string, opts *UpdateDomainOptions) error {
-	r := newHTTPRequest(generateApiUrl(mg, 4, domainsEndpoint) + "/" + name)
+func (mg *Client) UpdateDomain(ctx context.Context, domain string, opts *UpdateDomainOptions) error {
+	r := newHTTPRequest(generateApiUrl(mg, 4, domainsEndpoint) + "/" + domain)
 	r.setClient(mg.HTTPClient())
 	r.setBasicAuth(basicAuthUser, mg.APIKey())
 
@@ -270,7 +281,13 @@ func (mg *Client) UpdateDomain(ctx context.Context, name string, opts *UpdateDom
 			payload.addValue("web_scheme", opts.WebScheme)
 		}
 		if opts.WebPrefix != "" {
-			payload.addValue("web_prefix", opts.WebScheme)
+			payload.addValue("web_prefix", opts.WebPrefix)
+		}
+		if opts.RequireTLS != nil {
+			payload.addValue("require_tls", boolToString(*opts.RequireTLS))
+		}
+		if opts.SkipVerification != nil {
+			payload.addValue("skip_verification", boolToString(*opts.SkipVerification))
 		}
 	}
 
diff --git a/domains_connection.go b/domains_connection.go
index eb61c27..6e4214b 100644
--- a/domains_connection.go
+++ b/domains_connection.go
@@ -7,6 +7,8 @@ import (
 )
 
 // GetDomainConnection returns delivery connection settings for the defined domain
+// Deprecated: use GetDomain instead
+// TODO(v6): remove
 func (mg *Client) GetDomainConnection(ctx context.Context, domain string) (mtypes.DomainConnection, error) {
 	r := newHTTPRequest(generateApiUrl(mg, 3, domainsEndpoint) + "/" + domain + "/connection")
 	r.setClient(mg.HTTPClient())
@@ -17,6 +19,8 @@ func (mg *Client) GetDomainConnection(ctx context.Context, domain string) (mtype
 }
 
 // UpdateDomainConnection updates the specified delivery connection settings for the defined domain
+// Deprecated: use UpdateDomain instead
+// TODO(v6): remove
 func (mg *Client) UpdateDomainConnection(ctx context.Context, domain string, settings mtypes.DomainConnection) error {
 	r := newHTTPRequest(generateApiUrl(mg, 3, domainsEndpoint) + "/" + domain + "/connection")
 	r.setClient(mg.HTTPClient())
diff --git a/mailgun.go b/mailgun.go
index daba0db..07a7bc4 100644
--- a/mailgun.go
+++ b/mailgun.go
@@ -152,12 +152,17 @@ type Mailgun interface {
 
 	ListDomains(opts *ListDomainsOptions) *DomainsIterator
 	GetDomain(ctx context.Context, domain string, opts *GetDomainOptions) (mtypes.GetDomainResponse, error)
-	CreateDomain(ctx context.Context, name string, opts *CreateDomainOptions) (mtypes.GetDomainResponse, error)
-	DeleteDomain(ctx context.Context, name string) error
-	VerifyAndReturnDomain(ctx context.Context, name string) (mtypes.GetDomainResponse, error)
+	CreateDomain(ctx context.Context, domain string, opts *CreateDomainOptions) (mtypes.GetDomainResponse, error)
+	VerifyDomain(ctx context.Context, domain string) (mtypes.GetDomainResponse, error)
+	UpdateDomain(ctx context.Context, domain string, opts *UpdateDomainOptions) error
+	DeleteDomain(ctx context.Context, domain string) error
+	// Deprecated: use VerifyDomain instead.
+	VerifyAndReturnDomain(ctx context.Context, domain string) (mtypes.GetDomainResponse, error)
 	ListIPDomains(ip string, opts *ListIPDomainOptions) *IPDomainsIterator
 
+	// Deprecated: use UpdateDomain instead
 	UpdateDomainConnection(ctx context.Context, domain string, dc mtypes.DomainConnection) error
+	// Deprecated: use GetDomain instead
 	GetDomainConnection(ctx context.Context, domain string) (mtypes.DomainConnection, error)
 
 	GetDomainTracking(ctx context.Context, domain string) (mtypes.DomainTracking, error)
diff --git a/mtypes/domains.go b/mtypes/domains.go
index 21557df..673895e 100644
--- a/mtypes/domains.go
+++ b/mtypes/domains.go
@@ -12,6 +12,12 @@ const (
 
 type SpamAction string
 
+type ListDomainsResponse struct {
+	// is -1 if Next() or First() have not been called
+	TotalCount int      `json:"total_count"`
+	Items      []Domain `json:"items"`
+}
+
 // A Domain structure holds information about a domain used when sending mail.
 type Domain struct {
 	CreatedAt                  RFC2822Time `json:"created_at"`
diff --git a/mtypes/domains_connection.go b/mtypes/domains_connection.go
index e12ba8e..beec036 100644
--- a/mtypes/domains_connection.go
+++ b/mtypes/domains_connection.go
@@ -1,16 +1,12 @@
 package mtypes
 
+// TODO(v6): remove this file
+
 type DomainConnectionResponse struct {
 	Connection DomainConnection `json:"connection"`
 }
 
-type ListDomainsResponse struct {
-	// is -1 if Next() or First() have not been called
-	TotalCount int      `json:"total_count"`
-	Items      []Domain `json:"items"`
-}
-
-// Specify the domain connection options
+// DomainConnection specifies the domain connection options.
 type DomainConnection struct {
 	RequireTLS       bool `json:"require_tls"`
 	SkipVerification bool `json:"skip_verification"`


Test patch:
diff --git a/domains_test.go b/domains_test.go
index ece44ae..c2de24e 100644
--- a/domains_test.go
+++ b/domains_test.go
@@ -105,6 +105,6 @@ func TestDomainVerify(t *testing.T) {
 
 	ctx := context.Background()
 
-	_, err = mg.VerifyAndReturnDomain(ctx, testDomain)
+	_, err = mg.VerifyDomain(ctx, testDomain)
 	require.NoError(t, err)
 }