Link Validation

The Link Validation API processes a list of URLs to verify their HTTP status, monitor redirect chains with timing metrics, and provide detailed information on content length, content type, and SSL certificate status.

Get Link Validation Results

Returns the results of a link validation test.

SecuritybasicAuth

Request

path Parameters

required

string

The ID of the validation test we want to check the results for

Responses

200

A 200 response

Response Schema: application/json

	object
	object

401

A 401 response

404

A 404 response

get/v1/inspect/links/{id}

Request samples

Response samples

application/json

{"meta": {"status": "Completed"
},
"items": {"id": "677eeda04fc661c900945dec",
"results": [{"url": "http://www.mailgun.com?utm_source=mailgun&utm_medium=email&utm_campaign=mailgun",
"status": "Valid",
"status_code": 200,
"passes": [{"id": "http_status_check",
"rule": "Valid HTTP Response",
"description": "Link returned a 2xx status",
"details": [{"status_code": 200
}
]
},
{"id": "ssl_certificate_check",
"rule": "SSL Certificate Valid",
"description": "SSL certificate is valid and not expiring soon",
"details": [{"common_name": "*.mailgun.com",
"expires_on": "2025-05-27T23:59:59Z"
}
]
},
{"id": "redirect_check",
"rule": "Redirect Check",
"description": "Redirect chain is within allowed limits and no loop detected",
"details": [{"final_url": "https://www.mailgun.com",
"redirect_count": 0
}
]
},
{"id": "response_time_check",
"rule": "Fast Response Time",
"description": "Link responded quickly",
"details": [{"time_elapsed": "209.914666ms"
}
]
}
],
"failures": [{"id": "http_status_check",
"rule": "Broken Link",
"description": "URL returned an error status",
"impact": "critical",
"recommendation": "Verify the destination URL is correct and accessible.",
"details": [{"status_code": 500,
"url": "https://www.brokenlink.com"
}
]
},
{"id": "ssl_certificate_check",
"rule": "Missing SSL Certificate",
"description": "No SSL certificate was found for the link",
"impact": "critical",
"recommendation": "Ensure the server provides a valid SSL certificate.",
"details": [{"url": "https://www.nosslcert.com"
}
]
}
],
"informational": [{"id": "content_type_check",
"rule": "Content Type",
"description": "Detected MIME type",
"details": [{"content_type": "text/html"
}
]
},
{"id": "content_length_check",
"rule": "Content Length",
"description": "Size of the page in bytes",
"details": [{"content_length": "5682"
}
]
},
{"id": "ga_tags_check",
"rule": "Google Analytics Tags Present",
"description": "UTM parameters found in the URL",
"details": [{"tags": ["utm_source",
"utm_medium",
"utm_campaign"
]
}
]
}
]
}
]
}
}

Reprocess Link Validation Test

Reprocess a link validation test.

SecuritybasicAuth

Request

path Parameters

required

string

Link Validation Test ID

Responses

200

A 200 response

Response Schema: application/json

	object
	object

400

A 400 response

401

A 401 response

post/v1/inspect/links/{id}

Request samples

Response samples

application/json

{"meta": {"status": "Processing"
},
"items": {"id": "67803c4b7061304b609e47d0",
"links": {"self": "https://api.mailgun.com/v1/inspect/links/67803c4b7061304b609e47d0"
}
}
}

Delete Link Validation Test

Delete a specific link validation test by its unique test ID. This endpoint allows you to remove a link validation test from the system. If the test ID does not exist, the appropriate error message is returned.

SecuritybasicAuth

Request

path Parameters

required

string

The unique identifier of the test.

Responses

200

A 200 response

Response Schema: application/json

message

required

string

401

A 401 response

404

A 404 response

delete/v1/inspect/links/{id}

Request samples

Response samples

application/json

{"message": "Test <id> has been successfully deleted."
}

List Link Validations

Retrieve a list of previous link validation tests based on various filters.

SecuritybasicAuth

Request

query Parameters

status	string Filter by status of the link validation test
id	string Filter by ID
url	string Search by URL
isExpiredSSL	string Filter by tests that contain expired SSL certificates
statusCode	integer Filter by tests with a particular status code

Responses

200

A 200 response

Response Schema: application/json

	object
	object
	Array of objects

400

A 400 response

401

A 401 response

get/v1/inspect/links

Request samples

Response samples

application/json

{"meta": {"count": 1
},
"paging": {"previous": "https://api.mailgun.com/v1/inspect/links?page=eyJzIjowLCJiIjoiNjc4MDNlYzM3MDYxMzA0YjYwOWU0N2Q3IiwicCI6dHJ1ZX0",
"first": "https://api.mailgun.com/v1/inspect/links?page=eyJzIjowLCJwIjpmYWxzZX0",
"next": "https://api.mailgun.com/v1/inspect/links?page=eyJzIjowLCJiIjoiNjc4MDNlYzM3MDYxMzA0YjYwOWU0N2Q3IiwicCI6ZmFsc2V9",
"last": "https://api.mailgun.com/v1/inspect/links?page=eyJzIjowLCJwIjp0cnVlfQ"
},
"items": [{"id": "67803ec37061304b609e47d7",
"results": [{"url": "http://www.mailgun.com?utm_source=mailgun&utm_medium=email&utm_campaign=mailgun",
"status": "Valid",
"status_code": 200,
"passes": [{"id": "http_status_check",
"rule": "Valid HTTP Response",
"description": "Link returned a 2xx status",
"details": [{"status_code": 200
}
]
},
{"id": "ssl_certificate_check",
"rule": "SSL Certificate Valid",
"description": "SSL certificate is valid and not expiring soon",
"details": [{"common_name": "*.mailgun.com",
"expires_on": "2025-05-27T23:59:59Z"
}
]
},
{"id": "redirect_check",
"rule": "Redirect Check",
"description": "Redirect chain is within allowed limits and no loop detected",
"details": [{"final_url": "https://www.mailgun.com",
"redirect_count": 0
}
]
},
{"id": "response_time_check",
"rule": "Fast Response Time",
"description": "Link responded quickly",
"details": [{"time_elapsed": "209.914666ms"
}
]
}
],
"failures": [{"id": "http_status_check",
"rule": "Broken Link",
"description": "URL returned an error status",
"impact": "critical",
"recommendation": "Verify the destination URL is correct and accessible.",
"details": [{"status_code": 500,
"url": "https://www.brokenlink.com"
}
]
},
{"id": "ssl_certificate_check",
"rule": "Missing SSL Certificate",
"description": "No SSL certificate was found for the link",
"impact": "critical",
"recommendation": "Ensure the server provides a valid SSL certificate.",
"details": [{"url": "https://www.nosslcert.com"
}
]
}
],
"informational": [{"id": "content_type_check",
"rule": "Content Type",
"description": "Detected MIME type",
"details": [{"content_type": "text/html"
}
]
},
{"id": "content_length_check",
"rule": "Content Length",
"description": "Size of the page in bytes",
"details": [{"content_length": "5682"
}
]
},
{"id": "ga_tags_check",
"rule": "Google Analytics Tags Present",
"description": "UTM parameters found in the URL",
"details": [{"tags": ["utm_source",
"utm_medium",
"utm_campaign"
]
}
]
}
]
}
]
}
]
}

Create a Link Validation Test

Create a link validation test.

SecuritybasicAuth

Request

Request Body schema: application/json
required

links required	Array of strings
userAgent required	string

Responses

200

A 200 response

Response Schema: application/json

	object
	object

400

A 400 response

401

A 401 response

post/v1/inspect/links

Request samples

application/json

{"links": ["string"
],
"userAgent": "string"
}

Response samples

application/json

{"meta": {"status": "Processing"
},
"items": {"id": "67803c4b7061304b609e47d0",
"links": {"self": "https://api.mailgun.com/v1/inspect/links/67803c4b7061304b609e47d0"
}
}
}

Validates link test results against the provided spreadsheet file

Compares link validation test results to the spreadsheet provided as a CSV, XLS or XLSX file.

SecuritybasicAuth

Request

Request Body schema: multipart/form-data
required

string

Responses

200

A 200 response

Response Schema: application/json

	object
	object

400

A 400 response

401

A 401 response

post/v1/inspect/links/{id}/csv

Request samples

multipart/form-data

expected file upload with key 'csv'

Response samples

application/json

{"meta": {"status": "Complete"
},
"items": {"errors": [{"row": 4,
"message": "final redirect mismatch: expected 'https://en.wikipedia.org/wiki', got 'https://en.wikipedia.org/wiki2'",
"alert": {"severity": "Critical",
"data": {"destination URL": "https://en.wikipedia.org/wiki",
"row": "4",
"spreadsheet URL": "https://en.wikipedia.org/wiki",
"spreadsheet destination URL": "https://en.wikipedia.org/wiki2",
"test URL": "https://en.wikipedia.org/wiki"
}
}
}
]
}
}

Cookie Policy GDPR Email Compliance Acceptable Use Policy Terms of Service Privacy Policy

Link Validation

Get Link Validation Results

path Parameters

Response Schema: application/json

Reprocess Link Validation Test

path Parameters

Response Schema: application/json

Delete Link Validation Test

path Parameters

Response Schema: application/json

List Link Validations

query Parameters

Response Schema: application/json

Create a Link Validation Test

Request Body schema: application/jsonrequired

Response Schema: application/json

Validates link test results against the provided spreadsheet file

Request Body schema: multipart/form-datarequired

Response Schema: application/json

Request Body schema: application/json
required

Request Body schema: multipart/form-data
required