# Email Preview API Mailgun Email Preview service with RESTful JSON HTTP API for providing email previews. Version: 1.0.0 ## Servers US Mailgun ``` https://api.mailgun.net ``` EU Mailgun ``` https://api.eu.mailgun.net ``` ## Security ### basicAuth HTTP Basic auth using api:YOUR_API_KEY. See [documentation](https://documentation.mailgun.com/docs/mailgun/api-reference/authentication/) Type: http Scheme: basic ## Download OpenAPI description [Email Preview API](https://documentation.mailgun.com/_spec/docs/inspect/api-reference/openapi-final.yaml) ## Email Preview This API provides functionality to create and manage email preview tests, as well as create shareable links. ### List Clients - [GET /v1/preview/tests/clients](https://documentation.mailgun.com/docs/inspect/api-reference/openapi-final/email-preview/get-v1-preview-tests-clients.md): Returns a list of clients that can perform an email preview. ### Get Test Results - [GET /v1/preview/tests/{test_id}/results](https://documentation.mailgun.com/docs/inspect/api-reference/openapi-final/email-preview/get-v1-preview-tests--test-id--results.md): Returns the results for the specified email preview test. ### Reprocess Emailpreview Test - [PUT /v1/preview/tests/{test_id}/results/reprocess](https://documentation.mailgun.com/docs/inspect/api-reference/openapi-final/email-preview/put-v1-preview-tests--test-id--results-reprocess.md): Reprocesses the test for the passed clients. ### Get Test Content (empty) - [GET /v1/preview/tests/{test_id}/content](https://documentation.mailgun.com/docs/inspect/api-reference/openapi-final/email-preview/get-v1-preview-tests--test-id--content.md): Gets HTML content of the passed test. ### Get Test Content - [GET /v1/preview/tests/{test_id}/content/{content}](https://documentation.mailgun.com/docs/inspect/api-reference/openapi-final/email-preview/get-v1-preview-tests--test-id--content--content-.md): Gets HTML content of the passed test. ### Generate Preview Address - [POST /v1/preview/address](https://documentation.mailgun.com/docs/inspect/api-reference/openapi-final/email-preview/post-v1-preview-address.md): Returns or generates an account's email preview address. ### List/Search Tests V2 - [GET /v2/preview/tests](https://documentation.mailgun.com/docs/inspect/api-reference/openapi-final/email-preview/get-v2-preview-tests.md): This call returns a list of Email Tests along with metadata about each test. Email Tests are stored for 90 days. When query parameters are provided, only the tests matching the specified criteria will be returned; otherwise, all available tests are returned. The response structure remains identical in both cases. ### Create Email Preview Test V2 - [POST /v2/preview/tests](https://documentation.mailgun.com/docs/inspect/api-reference/openapi-final/email-preview/post-v2-preview-tests.md): This call creates a new email test and submits it to our system for processing.All requests must contain a subject property and one source property (either html or url). All other properties are optional. In the following table, each property and its default value is shown. If content-checking variables (such as those for link validation, image validation, or accessibility) are set in the body of the request, the endpoint will run content-checking on the email content. The response will include an id property that should be used to request the results or trigger further processes on the email content.For enterprise customers, the response will also include the customer_id and reference_id that were submitted with the test. ### Get Test Results by client ID V2 - [GET /v2/preview/tests/{test_id}/results/{client_id}](https://documentation.mailgun.com/docs/inspect/api-reference/openapi-final/email-preview/get-v2-preview-tests--test-id--results--client-id-.md): This call returns detailed results for screenshots including their upload locations, send times, completion times, and information about bounces, if any. is a test ID returned from test creation or the get test list functions. The is required and restricts the returned data exclusively to the specified client. If the client is not present in the test or is invalid, an error will be returned. ### Get Emailpreview Test Information V2 - [GET /v2/preview/tests/{test_id}](https://documentation.mailgun.com/docs/inspect/api-reference/openapi-final/email-preview/get-v2-preview-tests--test-id-.md): Retrieves detailed information about a specific test, including the subject, submission time (in UNIX timestamp format), processing statuses, and any content checking results. The response includes one to three properties containing arrays of clients: completed (clients that have successfully uploaded screenshots), processing (clients that are still being processed by our system), and bounced (clients that were bounced by the destination and cannot be retried). Additionally, the system will automatically requeue screenshots if they remain in processing for more than three minutes. ### Delete Emailpreview Test V2 - [DELETE /v2/preview/tests/{test_id}](https://documentation.mailgun.com/docs/inspect/api-reference/openapi-final/email-preview/delete-v2-preview-tests--test-id-.md): Deletes the specified test and its content checking. Once it is deleted, it cannot be recovered. ### Retrieve Export Job Details for Email Preview Test Screenshots - [GET /v2/preview/tests/{test_id}/exports/{job_id}](https://documentation.mailgun.com/docs/inspect/api-reference/openapi-final/email-preview/get-v2-preview-tests--test-id--exports--job-id-.md): Retrieves the status and details of an export job created to collect screenshots for an Email Preview Test. Provide both the test ID and the job ID to fetch the export job information. ### Retrieve Export Job Details for Email Preview Test Screenshots - [GET /v2/preview/tests/{test_id}/exports](https://documentation.mailgun.com/docs/inspect/api-reference/openapi-final/email-preview/get-v2-preview-tests--test-id--exports.md): Retrieves the status and details of an export job created to collect screenshots for an Email Preview Test. Provide the test ID to fetch the latest export job information. ### Create Export Job for Email Preview Test Screenshots - [POST /v2/preview/tests/{test_id}/exports](https://documentation.mailgun.com/docs/inspect/api-reference/openapi-final/email-preview/post-v2-preview-tests--test-id--exports.md): Initiates an export job that collects screenshots for a specified Email Preview Test. Provide the list of client IDs whose screenshots you want to export. The job status can be monitored using the job ID returned in the response. ### Create PreviewShare - [POST /v1/preview/sharing](https://documentation.mailgun.com/docs/inspect/api-reference/openapi-final/email-preview/post-v1-preview-sharing.md): Create a shareable link to an email preview test. ### Get PreviewShare - [GET /v1/preview/sharing/{test_id}](https://documentation.mailgun.com/docs/inspect/api-reference/openapi-final/email-preview/get-v1-preview-sharing--test-id-.md): Returns PreviewShare record by TID. ### Update PreviewShare - [PUT /v1/preview/sharing/{test_id}](https://documentation.mailgun.com/docs/inspect/api-reference/openapi-final/email-preview/put-v1-preview-sharing--test-id-.md): Updates PreviewShare record enabled field. ### Delete PreviewShare - [DELETE /v1/preview/sharing/{test_id}](https://documentation.mailgun.com/docs/inspect/api-reference/openapi-final/email-preview/delete-v1-preview-sharing--test-id-.md): Delete PreviewShare record by TID. ### Rotate PreviewShare - [POST /v1/preview/sharing/{test_id}/rotate](https://documentation.mailgun.com/docs/inspect/api-reference/openapi-final/email-preview/post-v1-preview-sharing--test-id--rotate.md): Re-generates the uuid and share url, and resets the expiration. ### Returns PreviewShare record by UUID. - [GET /v1/preview/sharing/public/{id}](https://documentation.mailgun.com/docs/inspect/api-reference/openapi-final/email-preview/get-v1-preview-sharing-public--id-.md) ### List Emailpreview Tests (deprecated) - [GET /v1/preview/tests](https://documentation.mailgun.com/docs/inspect/api-reference/openapi-final/email-preview/get-v1-preview-tests.md): Returns a list of email preview tests. _This endpoint is deprecated in favor of our V2 endpoint._ ### Create Emailpreview Test (deprecated) - [POST /v1/preview/tests](https://documentation.mailgun.com/docs/inspect/api-reference/openapi-final/email-preview/post-v1-preview-tests.md): Creates a new email preview test. _This endpoint is deprecated in favor of our V2 endpoint._ ### Get Emailpreview Test Info (deprecated) - [GET /v1/preview/tests/{test_id}](https://documentation.mailgun.com/docs/inspect/api-reference/openapi-final/email-preview/get-v1-preview-tests--test-id-.md): Returns test info. _This endpoint is deprecated in favor of our V2 endpoint._ ### Delete Emailpreview Test (deprecated) - [DELETE /v1/preview/tests/{test_id}](https://documentation.mailgun.com/docs/inspect/api-reference/openapi-final/email-preview/delete-v1-preview-tests--test-id-.md): Deletes the specified test. _This endpoint is deprecated in favor of our V2 endpoint._ ## 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 - [GET /v1/inspect/links/{id}](https://documentation.mailgun.com/docs/inspect/api-reference/openapi-final/link-validation/get-v1-inspect-links--id-.md): Returns the results of a link validation test. ### Reprocess Link Validation Test - [POST /v1/inspect/links/{id}](https://documentation.mailgun.com/docs/inspect/api-reference/openapi-final/link-validation/post-v1-inspect-links--id-.md): Reprocess a link validation test. ### Delete Link Validation Test - [DELETE /v1/inspect/links/{id}](https://documentation.mailgun.com/docs/inspect/api-reference/openapi-final/link-validation/delete-v1-inspect-links--id-.md): 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. ### List Link Validations - [GET /v1/inspect/links](https://documentation.mailgun.com/docs/inspect/api-reference/openapi-final/link-validation/get-v1-inspect-links.md): Retrieve a list of previous link validation tests based on various filters. ### Create a Link Validation Test - [POST /v1/inspect/links](https://documentation.mailgun.com/docs/inspect/api-reference/openapi-final/link-validation/post-v1-inspect-links.md): Create a link validation test. ### Create a Link Validation Test - [POST /v1/inspect/links/html-validate](https://documentation.mailgun.com/docs/inspect/api-reference/openapi-final/link-validation/post-v1-inspect-links-html-validate.md): Create a link validation test. ### Validates link test results against the provided spreadsheet file - [POST /v1/inspect/links/{id}/csv](https://documentation.mailgun.com/docs/inspect/api-reference/openapi-final/link-validation/post-v1-inspect-links--id--csv.md): Compares link validation test results to the spreadsheet provided as a CSV, XLS or XLSX file. ## 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 - [GET /v1/inspect/images/{id}](https://documentation.mailgun.com/docs/inspect/api-reference/openapi-final/image-validation/get-v1-inspect-images--id-.md): Returns the results of an image validation test. ### Delete Image Validation Test - [DELETE /v1/inspect/images/{id}](https://documentation.mailgun.com/docs/inspect/api-reference/openapi-final/image-validation/delete-v1-inspect-images--id-.md): 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. ### Get Image Validation Tests - [GET /v1/inspect/images](https://documentation.mailgun.com/docs/inspect/api-reference/openapi-final/image-validation/get-v1-inspect-images.md): 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'. ### Create an Image Validation Test - [POST /v1/inspect/images](https://documentation.mailgun.com/docs/inspect/api-reference/openapi-final/image-validation/post-v1-inspect-images.md): Create an image validation test. ### Create an Image Validation Test by HTML - [POST /v1/inspect/images/html-validate](https://documentation.mailgun.com/docs/inspect/api-reference/openapi-final/image-validation/post-v1-inspect-images-html-validate.md): Create an image validation test with HTML ### Create an Image Validation Test by Image Upload - [POST /v1/inspect/images/upload](https://documentation.mailgun.com/docs/inspect/api-reference/openapi-final/image-validation/post-v1-inspect-images-upload.md): Create an image validation test by image upload ### Reprocess Image Validation Test - [POST /v1/inspect/images/{id}/reprocess](https://documentation.mailgun.com/docs/inspect/api-reference/openapi-final/image-validation/post-v1-inspect-images--id--reprocess.md): Reprocess an image validation test. ### Optimize Images By Test ID - [POST /v1/inspect/images/{id}/optimize](https://documentation.mailgun.com/docs/inspect/api-reference/openapi-final/image-validation/post-v1-inspect-images--id--optimize.md): Optimizes images by test id ### Optimize Single Image By Test ID - [POST /v1/inspect/images/{id}/optimize/{image_id}](https://documentation.mailgun.com/docs/inspect/api-reference/openapi-final/image-validation/post-v1-inspect-images--id--optimize--image-id-.md): Optimizes a single image by test id ## Accessibility The Accessibility API evaluates HTML emails against WCAG standards, providing a clear pass/fail assessment to ensure compliance with accessibility guidelines. ### Get Accessibility Tests - [GET /v1/inspect/accessibility](https://documentation.mailgun.com/docs/inspect/api-reference/openapi-final/accessibility/get-v1-inspect-accessibility.md): Retrieve a paginated list of all accessibility tests that have been submitted. Each test includes details such as its status, the number of checks performed, and, of those checks, how many passes and failures there were. 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'. ### Create Accessibility Test - [POST /v1/inspect/accessibility](https://documentation.mailgun.com/docs/inspect/api-reference/openapi-final/accessibility/post-v1-inspect-accessibility.md): This endpoint allows users to submit an accessibility test for processing. It accepts a set of HTML content, processes it for accessibility issues, and returns a unique job ID for tracking the status of the test. The status of the job will display in the meta object, with a status of 'Processing'. ### Get Accessibility Test - [GET /v1/inspect/accessibility/{id}](https://documentation.mailgun.com/docs/inspect/api-reference/openapi-final/accessibility/get-v1-inspect-accessibility--id-.md): Retrieve the details of a specific accessibility test using the provided test ID. This endpoint returns comprehensive details about the test, including metadata and test results. ### Delete Accessibility Test - [DELETE /v1/inspect/accessibility/{id}](https://documentation.mailgun.com/docs/inspect/api-reference/openapi-final/accessibility/delete-v1-inspect-accessibility--id-.md): Delete a specific accessibility test by its unique test ID. This endpoint allows you to remove an accessibility test from the system. If the test ID does not exist, the appropriate error message is returned.