Domain Tracking

Mailgun offers tracking for clicks, unsubscribes, and opens, with optional HTTPS protocol support on tracking URLs. To enable HTTPS, Mailgun uses Let’s Encrypt with HTTP-01 challenges through your existing tracking CNAME record to issue a TLS certificate. This setup also includes support for HTTP Strict Transport Security (HSTS) for enhanced security.

Get tracking settings

get/v3/domains/{name}/tracking

Use to check if open, click and unsubscribe tracking are active/inactive.

SecuritybasicAuth
Request
path Parameters
name
required
string

The name of the domain to fetch tracking details for.

Responses
200

A 200 response

Response Schema: application/json
required
object
required
object
required
object
required
object
web_scheme
required
string
401

A 401 response

404

A 404 response

Request samples 
Response samples 
application/json
{
  • "tracking": {
    • "open": {
      },
    • "click": {
      },
    • "unsubscribe": {
      },
    • "web_scheme": "http"
    }
}
Update click tracking settings
put/v3/domains/{name}/tracking/click
Use to turn on/off the click tracking at the domain level.


SecuritybasicAuth 
Request 
path Parameters
name
required
string
The name of the domain you want to update


 
Request Body schema: multipart/form-data
required
active
string
Set param to htmlonly, true, or false.  Omit this param to make no change to the active status. Click tracking is consider as active if it's in the 'htmlonly' or 'true' state


 
Responses 
200
A 200 response


Response Schema: application/json
message
required
string
 
required
object
 
401
A 401 response


404
A 404 response


Request samples 
Response samples 
application/json
{
  • "message": "Domain tracking settings have been updated",
  • "click": {
    • "active": true
    }
}
Update open tracking settings
put/v3/domains/{name}/tracking/open
Use to turn on/off the open tracking at the domain level.


SecuritybasicAuth 
Request 
path Parameters
name
required
string
The name of the domain you want to update


 
Request Body schema: multipart/form-data
required
active
boolean
Set this param to true or false to toggle open tracking active status. Omit this param to keep current settings.


 
place_at_the_top
boolean
Setting this param to true will place the open tracking pixel at the top of the HTML body when inserted into the email mime. Omit this param to keep current setting.


 
Responses 
200
A 200 response


Response Schema: application/json
message
required
string
 
required
object
 
401
A 401 response


404
A 404 response


Request samples 
Response samples 
application/json
{
  • "message": "Domain tracking settings have been updated",
  • "open": {
    • "active": true
    }
}
Update unsubscribe tracking settings
put/v3/domains/{name}/tracking/unsubscribe
Use to turn on/off the unsubscribe tracking at the domain level.


SecuritybasicAuth 
Request 
path Parameters
name
required
string
The name of the domain you want to update


 
Request Body schema: multipart/form-data
required
active
boolean
This param will toggle the active status of unsubscribe tracking on the domain.


 
html_footer
string
Updates the html footer for the unsubscribe link inserted into the email html part of the mime.


 
text_footer
string
Updates the text footer for the unsubscribe link inserted into the email plain part of the mime.


 
Responses 
200
A 200 response


Response Schema: application/json
message
required
string
 
required
object
 
401
A 401 response


404
A 404 response


Request samples 
Response samples 
application/json
{
  • "message": "Domain tracking settings have been updated",
  • "unsubscribe": {
    • "active": true,
    • "html_footer": "<br>\n<p><a href=\"%unsubscribe_url%\">unsubscribe</a></p>\n",
    • "text_footer": "To unsubscribe click: <%unsubscribe_url%>\n\n"
    }
}
Status of x509 TLS certificate
get/v2/x509/{domain}/status
Get x509 TLS certificate and status


SecuritybasicAuth 
Request 
path Parameters
domain
required
string
The tracking domain of the TLS certificate, formatted as webPrefix.domainName from domains settings


 
Responses 
200
A 200 response


Response Schema: application/json
status
required
object
 
error
required
string
 
certificate
string
 
404
A 404 response


Request samples 
Response samples 
application/json
{
  • "status": "expired",
  • "error": "x509 certificate has expired",
  • "certificate": "{CERT}"
}
Initiate regeneration of an expired x509 TLS certificate
put/v2/x509/{domain}
Initiates regeneration of an expired TLS certificate for the tracking domain in a background task.  Once generation is enqueued, you may poll status endpoint in location field to check for success.  This will not regenerate an existing certificate that is still valid


SecuritybasicAuth 
Request 
path Parameters
domain
required
string
The tracking domain of the TLS certificate, formatted as webPrefix.domainName from domains settings


 
Responses 
202
A 202 response


400
A 400 response


402
A 402 response


404
A 404 response


409
A 409 response


429
A 429 response


Request samples 
Response samples 
application/json
{
  • "message": "Initiated x509 key pair generation",
  • "location": "/v2/x509/example.com/status"
}
Initiate generation of an x509 TLS certificate
post/v2/x509/{domain}
Initiates generation of a TLS certificate for the tracking domain in a background task.  Once generation is enqueued, you may poll the status endpoint in location field to check for success


SecuritybasicAuth 
Request 
path Parameters
domain
required
string
The tracking domain of the TLS certificate, formatted as webPrefix.domainName from domains settings


 
Responses 
202
A 202 response


400
A 400 response


402
A 402 response


404
A 404 response


409
A 409 response


Request samples 
Response samples 
application/json
{
  • "message": "Initiated x509 key pair generation",
  • "location": "/v2/x509/example.com/status"
}
Cookie PolicyGDPR Email ComplianceAcceptable Use PolicyTerms of ServicePrivacy Policy
© 2024 Sinch Mailgun. All rights reserved.