Email Preview

This API provides functionality to create and manage email preview tests, as well as create shareable links.

List Clients

Returns a list of clients that can perform an email preview.

SecuritybasicAuth
Responses
200

A 200 response

Response Schema: application/json
required
object
additional property
object
id
required
string
client
required
string
os
required
string
category
required
string
browser
string
rotate
boolean
image_blocking
boolean
free
boolean
default
boolean
400

A 400 response

401

A 401 response

500

A 500 response

4xx

A 4xx response

get/v1/preview/tests/clients
Request samples 
Response samples 
application/json
{
  • "clients": {
    • "android10_gmailapp_pixel4_dm": {
      }
    }
}
List Emailpreview Tests
Returns a list of email preview tests.

WARNING: This endpoint is deprecated in favor of our V2 endpoint.


SecuritybasicAuth 
Responses 
200
A 200 response


Response Schema: application/json
id
string
 
date
integer <int32> 
 
type
string
 
subject
string
 
object
 
400
A 400 response


401
A 401 response


500
A 500 response


4xx
A 4xx response


get/v1/preview/tests
Request samples 
Response samples 
application/json
[
  • {
    • "id": "",
    • "date": 0,
    • "type": "",
    • "subject": "",
    • "headers": {
      }
    }
]
Create Emailpreview Test
Creates a new email preview test.

WARNING: This endpoint is deprecated in favor of our V2 endpoint.


SecuritybasicAuth 
Request 
Request Body schema: create
required
subject
required
string
 
html
string
 
mime
string
 
url
string
 
transfer_encoding
string
 
charset
string
 
reference_id
string
 
customer_id
string
 
clients
Array of strings
 
image_blocking
boolean
 
object
 
object
 
object
 
Responses 
200
A 200 response


Response Schema: application/json
id
string
 
reference_id
string
 
customer_id
string
 
object
 
Array of objects
 
object
 
400
A 400 response


401
A 401 response


500
A 500 response


4xx
A 4xx response


post/v1/preview/tests
Request samples 
create
{
  "subject": "some subject",
  "url": "https://example.com",
  "content_checking": {}
}
Response samples 
application/json
{
  • "id": "gmail"
}
Get Test Results
Returns the results for the specified email preview test.


SecuritybasicAuth 
Request 
path Parameters
test_id
required
string
Test to get results for


 
Responses 
200
A 200 response


Response Schema: application/json
additional property
object
 
id
string
 
display_name
string
 
client
string
 
os
string
 
category
string
 
browser
string
 
object
 
thumbnail
string
 
full_thumbnail
string
 
status
string
 
object
 
400
A 400 response


401
A 401 response


500
A 500 response


4xx
A 4xx response


get/v1/preview/tests/{test_id}/results
Request samples 
Response samples 
application/json
{}
Get Emailpreview Test Info
Returns test info.

WARNING: This endpoint is deprecated in favor of our V2 endpoint.


SecuritybasicAuth 
Request 
path Parameters
test_id
required
string
Test to get the content of


 
Responses 
200
A 200 response


Response Schema: application/json
subject
required
string
 
date
required
integer <int32> 
 
completed
Array of strings
 
processing
Array of strings
 
bounced
Array of strings
 
object
 
400
A 400 response


401
A 401 response


500
A 500 response


4xx
A 4xx response


get/v1/preview/tests/{test_id}
Request samples 
Response samples 
application/json
{
  • "subject": "string",
  • "date": 0,
  • "completed": [
    • "string"
    ],
  • "processing": [
    • "string"
    ],
  • "bounced": [
    • "string"
    ],
  • "content_checking": {
    • "link_validation": {
      },
    • "image_validation": {
      },
    • "accessibility": {
      }
    }
}
Delete Emailpreview Test
Deletes the specified test.

WARNING: This endpoint is deprecated in favor of our V2 endpoint.


SecuritybasicAuth 
Request 
path Parameters
test_id
required
string
Test to delete


 
Responses 
200
A 200 response


Response Schema: application/json
success
required
boolean
 
400
A 400 response


401
A 401 response


500
A 500 response


4xx
A 4xx response


delete/v1/preview/tests/{test_id}
Request samples 
Response samples 
application/json
{
  • "success": true
}
Reprocess Emailpreview Test
Reprocesses the test for the passed clients.


SecuritybasicAuth 
Request 
path Parameters
test_id
required
string
Test to reprocess


 
Responses 
200
A 200 response


Response Schema: application/json
additional property
object
 
regional
required
boolean
 
success
boolean
 
remaining_reprocesses
integer <int32> 
 
object
 
400
A 400 response


401
A 401 response


500
A 500 response


4xx
A 4xx response


put/v1/preview/tests/{test_id}/results/reprocess
Request samples 
Response samples 
application/json
null
Get Test Content (empty)
Gets HTML content of the passed test.


SecuritybasicAuth 
Request 
path Parameters
test_id
required
string
Test to get the content of


 
Responses 
200
A 200 response


Response Schema: application/json
content
required
string
 
400
A 400 response


401
A 401 response


500
A 500 response


4xx
A 4xx response


get/v1/preview/tests/{test_id}/content
Request samples 
Response samples 
application/json
{
  • "content": "string"
}
Get Test Content
Gets HTML content of the passed test.


SecuritybasicAuth 
Request 
path Parameters
test_id
required
string
Test to get the content of


 
content
string
Content to get: inlinecss or textonly


 
Responses 
200
A 200 response


Response Schema: application/json
content
required
string
 
400
A 400 response


401
A 401 response


500
A 500 response


4xx
A 4xx response


get/v1/preview/tests/{test_id}/content/{content}
Request samples 
Response samples 
application/json
{
  • "content": "string"
}
Generate Preview Address
Returns or generates an account's email preview address.


SecuritybasicAuth 
Responses 
200
A 200 response


Response Schema: application/json
preview_address
required
string
 
500
A 500 response


4xx
A 4xx response


post/v1/preview/address
Request samples 
Response samples 
application/json
{
  • "preview_address": "string"
}
List/Search Tests V2
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.


SecuritybasicAuth 
Request 
query Parameters
customer_id
string
Filter tests by the provided customer ID.


 
from
string
The starting point of your test date range. Accepts formats like '2025-03-10 17:52:07', Unix timestamp, or 'yesterday'.


 
to
string
The ending point of your test date range. Accepts formats like '2025-03-10 17:52:07', Unix timestamp, or 'yesterday'.


 
subject
string
The "subject" field of returned tests must contain the exact string. This search is case-insensitive.


 
headers
string
Enterprise users can use this field in a KV array of x-headers submitted with the test. This is an AND match, meaning all headers must be present to return.


 
results
integer
The number of results to return. Must be between 1 and 200. The default value is 50.


 
page
integer
The page number. If you submit a number higher than the number of pages in the data, an empty array will be returned. The default value is 1.


 
Responses 
200
A 200 response


Response Schema: application/json
id
string
 
date
integer <int32> 
 
type
string
 
subject
string
 
object
 
400
A 400 response


401
A 401 response


500
A 500 response


4xx
A 4xx response


get/v2/preview/tests
Request samples 
Response samples 
application/json
[
  • {
    • "id": "DdbNga1MdL3N7sO19v5MAmpOKIqFrLg9cgpCIgS4othXJ",
    • "date": 1739876826,
    • "type": "email-test",
    • "subject": "subject",
    • "headers": { }
    },
  • {
    • "id": "pDdLWjbj3ZbAnHkTbg3QG27mFyoc62OAH1WJXgmb0uNT4",
    • "date": 1739874606,
    • "type": "email-test",
    • "subject": "",
    • "headers": { }
    }
]
Create Email Preview Test V2
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.


SecuritybasicAuth 
Request 
Request Body schema: create
required
subject
required
string
 
html
string
 
mime
string
 
url
string
 
transfer_encoding
string
 
charset
string
 
reference_id
string
 
customer_id
string
 
clients
Array of strings
 
image_blocking
boolean
 
object
 
object
 
object
 
Responses 
200
A 200 response


Response Schema: application/json
id
string
 
reference_id
string
 
customer_id
string
 
object
 
Array of objects
 
object
 
400
A 400 response


401
A 401 response


500
A 500 response


4xx
A 4xx response


post/v2/preview/tests
Request samples 
create
{
  "subject": "Example subject",
  "html": "<html>...</html>",
  "transfer_encoding": "base64",
  "charset": "utf-8",
  "customer_id": "1",
  "clients": [
    "client1",
    "client2"
  ],
  "content_checking": {
    "link_validation": true,
    "image_validation": true,
    "accessibility": true
  }
}
Response samples 
application/json
{
  • "id": "exampleTestID",
  • "customer_id": "1",
  • "warnings": [
    • {
      }
    ],
  • "content_checking": {
    • "link_validation": {
      },
    • "image_validation": {
      },
    • "accessibility": {
      }
    }
}
Get Test Results by client ID V2
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.


SecuritybasicAuth 
Request 
path Parameters
test_id
required
string
Test to get results for


 
client_id
required
string
Client to get results for


 
Responses 
200
A 200 response


Response Schema: application/json
additional property
object
 
id
string
 
display_name
string
 
client
string
 
os
string
 
category
string
 
browser
string
 
object
 
thumbnail
string
 
full_thumbnail
string
 
status
string
 
object
 
400
A 400 response


401
A 401 response


500
A 500 response


4xx
A 4xx response


get/v2/preview/tests/{test_id}/results/{client_id}
Request samples 
Response samples 
application/json
{}
Get Emailpreview Test Information V2
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.


SecuritybasicAuth 
Request 
path Parameters
test_id
required
string
The ID of the test to retrieve


 
Responses 
200
A 200 response


Response Schema: application/json
subject
required
string
 
date
required
integer <int32> 
 
completed
Array of strings
 
processing
Array of strings
 
bounced
Array of strings
 
object
 
400
A 400 response


401
A 401 response


500
A 500 response


4xx
A 4xx response


get/v2/preview/tests/{test_id}
Request samples 
Response samples 
application/json
{
  • "subject": "Example Subject",
  • "date": 1739876826,
  • "completed": [
    • "client1"
    ],
  • "processing": [
    • "client2"
    ],
  • "bounced": [
    • "client3"
    ],
  • "content_checking": {
    • "link_validation": {
      },
    • "image_validation": {
      },
    • "accessibility": {
      }
    }
}
Delete Emailpreview Test V2
Deletes the specified test and its content checking. Once it is deleted, it cannot be recovered.


SecuritybasicAuth 
Request 
path Parameters
test_id
required
string
Test to delete


 
Responses 
200
A 200 response


Response Schema: application/json
success
required
boolean
 
400
A 400 response


401
A 401 response


500
A 500 response


4xx
A 4xx response


delete/v2/preview/tests/{test_id}
Request samples 
Response samples 
application/json
{
  • "success": true
}
Create PreviewShare
Create a shareable link to an email preview test.


SecuritybasicAuth 
Request 
Request Body schema: create
required
test_id
required
string
 
Responses 
200
A 200 response


Response Schema: application/json
message
required
string
 
500
A 500 response


4xx
A 4xx response


post/v1/preview/sharing
Request samples 
create
{
  "test_id": "some-id"
}
Response samples 
application/json
{
  • "message": "record created"
}
Get PreviewShare
Returns PreviewShare record by TID.


SecuritybasicAuth 
Request 
path Parameters
test_id
required
string
Test to get


 
Responses 
200
A 200 response


Response Schema: application/json
test_id
required
string
 
url_uuid
required
string
 
url
required
string
 
enabled
required
boolean
 
expires_at
required
string <date-time> 
 
500
A 500 response


4xx
A 4xx response


get/v1/preview/sharing/{test_id}
Request samples 
Response samples 
application/json
{
  • "test_id": "some-test-id",
  • "url_uuid": "some-uuid",
  • "url": "share.mailgun.com/email-previews/some-uuid",
  • "enabled": true,
  • "expires_at": "0001-01-01 00:00:00 +0000 UTC"
}
Update PreviewShare
Updates PreviewShare record enabled field.


SecuritybasicAuth 
Request 
path Parameters
test_id
required
string
Test to update


 
query Parameters
url_uuid
required
string
UUID to update


 
Responses 
200
A 200 response


Response Schema: application/json
message
required
string
 
500
A 500 response


4xx
A 4xx response


put/v1/preview/sharing/{test_id}
Request samples 
Response samples 
application/json
{
  • "message": "record updated"
}
Delete PreviewShare
Delete PreviewShare record by TID.


SecuritybasicAuth 
Request 
path Parameters
test_id
required
string
Test to delete


 
query Parameters
url_uuid
required
string
UUID to delete


 
Responses 
200
A 200 response


Response Schema: application/json
message
required
string
 
500
A 500 response


4xx
A 4xx response


delete/v1/preview/sharing/{test_id}
Request samples 
Response samples 
application/json
{
  • "message": "record deleted"
}
Rotate PreviewShare
Re-generates the uuid and share url, and resets the expiration.


SecuritybasicAuth 
Request 
path Parameters
test_id
required
string
Test to rotate


 
query Parameters
url_uuid
required
string
UUID to rotate


 
Responses 
200
A 200 response


Response Schema: application/json
test_id
required
string
 
url_uuid
required
string
 
url
required
string
 
enabled
required
boolean
 
expires_at
required
string <date-time> 
 
500
A 500 response


4xx
A 4xx response


post/v1/preview/sharing/{test_id}/rotate
Request samples 
Response samples 
application/json
{
  • "test_id": "some-test-id",
  • "url_uuid": "some-new-uuid",
  • "url": "share.mailgun.com/email-previews/some-new-uuid",
  • "enabled": true,
  • "expires_at": "0001-01-01 00:00:00 +0000 UTC"
}
Returns PreviewShare record by UUID.
SecuritybasicAuth 
Request 
path Parameters
id
required
string
UUID to get


 
Responses 
200
A 200 response


Response Schema: application/json
subject
required
string
 
date
required
integer <int32> 
 
required
Array of objects
 
500
A 500 response


4xx
A 4xx response


get/v1/preview/sharing/public/{id}
Request samples 
Response samples 
application/json
{
  • "subject": "some test",
  • "date": 1,
  • "results": [ ]
}
Cookie PolicyGDPR Email ComplianceAcceptable Use PolicyTerms of ServicePrivacy Policy
© 2024 Sinch Mailgun. All rights reserved.