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

Open tracking settings

required
object

Click tracking settings

required
object

Unsubscribe tracking settings

web_scheme
required
string

The web scheme for the domain

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
A message indicating success


 
required
object
Click settings


 
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
A message indicating success


 
required
object
Open settings


 
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
A message indicating success


 
required
object
Unsubscribe settings


 
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"
    }
}
Tracking Certificate: Get certificate and status
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 web_prefix.domain_name (web_prefix is configured in your domains settings)


 
Responses 
200
A 200 response


Response Schema: application/json
status
required
object
Status of certificate. Either 'expired' 'processing' 'active' or 'error'


 
error
required
string or null
An error message if an error occurred. Null if there is no error.


 
certificate
string
The x509 certificate in PEM format. Present only if the certificate status is 'active' 'error' or 'expired'


 
404
A 404 response


Request samples 
Response samples 
application/json
{
  • "status": "processing",
  • "error": "Waiting for x509 key pair generation"
}
Tracking Certificate: Regenerate expired 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"
}
Tracking Certificate: Generate
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.