Image Validation

The Image Validation API processes image URLs or uploads to provide comprehensive details such as dimensions, type, file size, and format, reports frame count, animation duration, color depth, and transparency for GIFs, and include image optimization capabilities.

Get Image Validation Results

Returns the results of an image 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/images/{id}

Request samples

Response samples

application/json

{"meta": {"status": "Completed"
},
"items": {"id": "67a654ba0f53254b9fdca3e2",
"images": [{"url": "https://onlinegiftools.com/images/examples-onlinegiftools/halloween-five-loops.gif",
"status": "Valid",
"passes": [{"id": "image_file_size_check",
"rule": "File Size Acceptable",
"description": "Image file size (2000 bytes) is within the acceptable limit",
"details": [{"file_size": 2000
}
]
}
],
"failures": [{"id": "load_time_check",
"rule": "Slow Load Time",
"description": "Image load time is 6000 ms, which exceeds the threshold of 2000 ms",
"impact": "moderate",
"recommendation": "Optimize the image or server performance to reduce load time.",
"details": [{"load_time_ms": 6000
}
]
}
],
"informational": [{"id": "image_format_check",
"rule": "Image Format Detected",
"description": "The detected format is JPEG",
"details": [{"format": "JPEG"
}
]
}
]
}
]
}
}

Delete Image Validation Test

Delete a specific image validation test by its unique test ID. This endpoint allows you to remove an image 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/images/{id}

Request samples

Response samples

application/json

{"message": "Image validation test with test id <id> has been successfully deleted."
}

Get Image Validation Tests

Retrieve a paginated list of all image validation tests that have been submitted. The response is paginated, with a limit of up to 1000 items per page. The total count of records will display in the meta object under the key, 'count'.

SecuritybasicAuth

Request

query Parameters

limit	integer Max count of items. Max: 1000. Default: 100
skip	integer Get the list of items starting at the nth element (paging). Default: 0

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/images

Request samples

Response samples

application/json

{"meta": {"count": 17
},
"paging": {"first": "https://api.mailgun.net/v1/inspect/accessibility/tests?limit=100&skip=0",
"last": "https://api.mailgun.net/v1/inspect/accessibility/tests?limit=100&skip=0"
},
"items": [{"id": "67a654ba0f53254b9fdca3e2",
"images": [{"id": "67a62ccd8824a77a474bc307",
"url": "https://onlinegiftools.com/images/examples-onlinegiftools/halloween-five-loops.gif",
"status": "Valid"
},
{"id": "67b625524b911fa30a4d784c",
"url": "https://media.tacdn.com/media/attractions-splice-spp-720x480/06/df/2c/9c.jpg",
"status": "Valid",
"-": {"alt": "Harlem Hip-Hop Walking Tour",
"width": "276",
"class": "image_resp image_style border_radius_8px",
"style": "width: 100% !important; height: auto !important; display: block; border-radius: 8px; -webkit-border-radius: 8px; -moz-border-radius: 8px; border-width: 0;"
}
}
]
}
]
}

Create an Image Validation Test

Create an image validation test.

SecuritybasicAuth

Request

Request Body schema: application/json
required

links

Array of strings

Responses

200

A 200 response

Response Schema: application/json

	object
	object

400

A 400 response

401

A 401 response

post/v1/inspect/images

Request samples

application/json

{ }

Response samples

application/json

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

Create an Image Validation Test by HTML

Create an image validation test with HTML

SecuritybasicAuth

Request

Request Body schema: application/json
required

html	string
url	string
mime	string
transfer_encoding	string
charset	string

Responses

200

A 200 response

Response Schema: application/json

	object
	object

400

A 400 response

401

A 401 response

post/v1/inspect/images/html-validate

Request samples

application/json

{ }

Response samples

application/json

{"meta": {"status": "Complete"
},
"items": {"id": "67b625524b911fa30a4d7858",
"links": {"self": "https://api.mailgun.com/v1/inspect/images/67b625524b911fa30a4d7858"
}
}
}

Create an Image Validation Test by Image Upload

Create an image validation test by image upload

SecuritybasicAuth

Request

Request Body schema: application/json
required

image

string <binary>

Responses

200

A 200 response

Response Schema: application/json

	object
	object

400

A 400 response

401

A 401 response

post/v1/inspect/images/upload

Request samples

application/json

{ }

Response samples

application/json

{"meta": {"status": "Complete"
},
"items": {"id": "67b629564b911fa30a4d7873",
"images": [{"id": "67b629564b911fa30a4d7872",
"status": "Valid"
}
]
}
}

Reprocess Image Validation Test

Reprocess an image validation test.

SecuritybasicAuth

Request

path Parameters

required

string

Test ID

Responses

200

A 200 response

Response Schema: application/json

	object
	object

400

A 400 response

401

A 401 response

post/v1/inspect/images/{id}/reprocess

Request samples

Response samples

application/json

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

Optimize Images By Test ID

Optimizes images by test id

SecuritybasicAuth

Request

path Parameters

required

string

The ID of the image validation test we want to optimize the images for.

Responses

200

A 200 response

Response Schema: application/json

	object
	object
	Array of objects

401

A 401 response

404

A 404 response

post/v1/inspect/images/{id}/optimize

Request samples

Response samples

application/json

{"meta": {"status": "Completed"
},
"items": [{"id": "67b5fc304b911fa30a4d7834",
"optimized_images": [{"id": "67b5fc304b911fa30a4d7835",
"original_image_id": "67a654ba0f53254b9fdca3e0",
"image_url": "https://onlinegiftools.com/images/examples-onlinegiftools/halloween-five-loops.gif",
"optimized_url": "https://storage.googleapis.com/mailforce-staging-mg-inspect/65a962eb2eab772ab72542ec/66c7bd142ac3f68383cea3e0/optimize/67b5fc304b911fa30a4d7835?X-Goog-Algorithm=GOOG4-RSA-SHA256&X-Goog-Credential=sa-mg-inspect%40mailforce-staging.iam.gserviceaccount.com%2F20250219%2Fauto%2Fstorage%2Fgoog4_request&X-Goog-Date=20250219T154345Z&X-Goog-Expires=604799&X-Goog-Signature=6d418ec5817f1b0e6f803356284af3c72bc2a39662bcde38b650666389b7122760b3a2d4f4e8884708edd37e69fd6c21fe3aae678558aa82e2bb98be951e4c5f7bfbb6b2c47f888f1921582e6095ba7fa5d1ccd2fd69df6a0f9842152ed22d1b85f1e865db83625f8a3d30c6a02e8c041a8a706e330d8218a40bbdbf841f79bf815261d15747a91b8d1e51de1f53d0f66b86150c92b7605396ca56bffb816ab7c4652cdecbf822bb967407a35abc19e28f2624004feb3f6e99b7f36b74c2cdea728fa50ec9bcecc6fe7d8fcb10b201f7d115dc6bacdc6ae5d4a475554a0717b3061d4a0150e97eb5fbc026924f6c76ac02e56721d7fb716ad00411df354ed13a&X-Goog-SignedHeaders=host",
"optimized_file_size": "361.16KB",
"optimized_mime_type": "image/gif",
"status": "Complete"
},
{"id": "67b5fc304b911fa30a4d7836",
"original_image_id": "67a654ba0f53254b9fdca3e1",
"image_url": "https://compote.slate.com/images/697b023b-64a5-49a0-8059-27b963453fb1.gif",
"optimized_url": "https://storage.googleapis.com/mailforce-staging-mg-inspect/65a962eb2eab772ab72542ec/66c7bd142ac3f68383cea3e0/optimize/67b5fc304b911fa30a4d7836?X-Goog-Algorithm=GOOG4-RSA-SHA256&X-Goog-Credential=sa-mg-inspect%40mailforce-staging.iam.gserviceaccount.com%2F20250219%2Fauto%2Fstorage%2Fgoog4_request&X-Goog-Date=20250219T154345Z&X-Goog-Expires=604799&X-Goog-Signature=791cb1ea8f1efd0646dd2b57afab2221d2a07da15c50ccad19c446b9e018ca657e2454b23427343300d7ab9e0aad10dabc92476f10e5f4c2a186e59b2c9298c14ba9ae00a86a65f3c97bcc30548b51bee1fb47b9652763a77d273d3b59a077feb93c0c6857b38de8d1314ec9496ebe5b8437d7898c7305d3d95b4716f8e4750d97a7d7132be2a388c3cfd4099a2a432ef7758a3d4187bf8cd104732fde5e49b63dc3cf58586a7833a88b12a5f77b561f606823955d6cdfb14f6f49e975ad9ac6b0cd883b28797fd15bfd20e4fdc211cc94539c61554b66954bbc4d6e6dcfe60b5dbc3474bd7a02f1a526b09766111b14ee7c6292a2b3756ec0535d01a8109678&X-Goog-SignedHeaders=host",
"optimized_file_size": "969.33KB",
"optimized_mime_type": "image/gif",
"status": "Complete"
}
]
}
]
}

Optimize Single Image By Test ID

Optimizes a single image by test id

SecuritybasicAuth

Request

path Parameters

test_id required	string The ID of the image validation test we want to optimize the images for.
image_id required	string The ID of the image we want to optimize

Responses

200

A 200 response

Response Schema: application/json

	object
	object
	object

401

A 401 response

404

A 404 response

post/v1/inspect/images/{id}/optimize/{image_id}

Request samples

Response samples

application/json

{"meta": {"status": "Completed"
},
"items": {"optimized_images": [{"id": "67b5fc304b911fa30a4d7836",
"original_image_id": "67b618d04b911fa30a4d783f",
"image_url": "https://compote.slate.com/images/697b023b-64a5-49a0-8059-27b963453fb1.gif",
"optimized_url": "https://storage.googleapis.com/mailforce-staging-mg-inspect/65a962eb2eab772ab72542ec/66c7bd142ac3f68383cea3e0/optimize/67b5fc304b911fa30a4d7836?X-Goog-Algorithm=GOOG4-RSA-SHA256&X-Goog-Credential=sa-mg-inspect%40mailforce-staging.iam.gserviceaccount.com%2F20250219%2Fauto%2Fstorage%2Fgoog4_request&X-Goog-Date=20250219T154345Z&X-Goog-Expires=604799&X-Goog-Signature=791cb1ea8f1efd0646dd2b57afab2221d2a07da15c50ccad19c446b9e018ca657e2454b23427343300d7ab9e0aad10dabc92476f10e5f4c2a186e59b2c9298c14ba9ae00a86a65f3c97bcc30548b51bee1fb47b9652763a77d273d3b59a077feb93c0c6857b38de8d1314ec9496ebe5b8437d7898c7305d3d95b4716f8e4750d97a7d7132be2a388c3cfd4099a2a432ef7758a3d4187bf8cd104732fde5e49b63dc3cf58586a7833a88b12a5f77b561f606823955d6cdfb14f6f49e975ad9ac6b0cd883b28797fd15bfd20e4fdc211cc94539c61554b66954bbc4d6e6dcfe60b5dbc3474bd7a02f1a526b09766111b14ee7c6292a2b3756ec0535d01a8109678&X-Goog-SignedHeaders=host",
"optimized_file_size": "969.33KB",
"optimized_mime_type": "image/gif",
"status": "Complete"
}
]
}
}

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

Image Validation

Get Image Validation Results

path Parameters

Response Schema: application/json

Delete Image Validation Test

path Parameters

Response Schema: application/json

Get Image Validation Tests

query Parameters

Response Schema: application/json

Create an Image Validation Test

Request Body schema: application/jsonrequired

Response Schema: application/json

Create an Image Validation Test by HTML

Request Body schema: application/jsonrequired

Response Schema: application/json

Create an Image Validation Test by Image Upload

Request Body schema: application/jsonrequired

Response Schema: application/json

Reprocess Image Validation Test

path Parameters

Response Schema: application/json

Optimize Images By Test ID

path Parameters

Response Schema: application/json

Optimize Single Image By Test ID

path Parameters

Response Schema: application/json

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required