Email Preview¶

Our Email Preview service allows you to see how your emails render across various web, desktop, and mobile clients.

Create Test¶

This call creates a new email preview 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.

The response will include an id property that should be used to request the results or run processes on the email content.

POST /v1/preview/tests

The available request fields are as follows:

Field	Description
`subject`	The subject line of your email, encoded as declared in `transfer_encoding`.
`html`	The email source of your email, encoded as declared in `transfer_encoding`.
`url`	A URL pointing to the email source of your email.
`clients`	An array of string IDs as returned from client list functions. If no clients are specified, all available clients will be used.
`reference_id`	This value can be used for searching and internal reporting.
`charset`	The character set your HTML is encoded in.
`transfer_encoding`	One of base64, quoted-printable, 7bit, or 8bit.

curl -X POST https://api.mailgun.net/v1/preview/tests \
  -F 'subject=test' \
  -F 'url=url' \
  --user 'api:<YOUR_API_KEY>'

import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.JsonNode;
import com.mashape.unirest.http.Unirest;
import com.mashape.unirest.http.exceptions.UnirestException;

public class MGSample {

    // ...

    public static JsonNode createTest() throws UnirestException {

        HttpResponse <JsonNode> request = Unirest.post("https://api.mailgun.net/v4/preview/tests")
            .basicAuth("api", API_KEY)
            .field("subject", "test")
            .field("url", "url")
            .asJson();

        return request.getBody();
    }
}

# Currently, the PHP SDK does not support the email preview endpoint.
# Consider using the following php curl function.
function create_email_previews() {
  $ch = curl_init();

  curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
  curl_setopt($ch, CURLOPT_USERPWD, 'api:PRIVATE_API_KEY');
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

  curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
  curl_setopt($ch, CURLOPT_URL, 'https://api.mailgun.net/v1/preview/tests');
  curl_setopt($ch, CURLOPT_POSTFIELDS, array(
      'subject'=> 'test',
      'url'=> 'url',
      )
  );

  $result = curl_exec($ch);
  curl_close($ch);

  return $result;
}

def create_email_previews():
    data = {'subject': 'test', 'url': 'url'}
    return requests.post(
        "https://api.mailgun.net/v1/preview/tests",
        data=json.dumps(data),
        auth=('api', 'YOUR_API_KEY'))

def create_email_previews
  data = { subject: "test", url: "url" }
  RestClient.post("https://api:YOUR_API_KEY@api.mailgun.net/v1/preview/tests",
                  fields_hash.merge(data))
end

using System;
using System.IO;
using RestSharp;
using RestSharp.Authenticators;

public class CreateEmailPreviewTests
{

    public static void Main (string[] args)
    {
        Console.WriteLine (CreateEmailPreview ().Content.ToString ());
    }

    public static IRestResponse CreateEmailPreview ()
    {
        RestClient client = new RestClient ();
        client.BaseUrl = new Uri ("https://api.mailgun.net");
        client.Authenticator =
            new HttpBasicAuthenticator ("api", "YOUR_API_KEY");
        RestRequest request = new RestRequest ();
        request.AddParameter ("subject", "test", ParameterType.UrlSegment);
        request.AddParameter ("url", "url", ParameterType.UrlSegment);
        request.Resource = "v1/preview/tests";
        request.Method = Method.POST;
        return client.Execute (request);
    }
}

Example response:

{
  "id": "<TEST_ID>",
  "reference_id": "123ABC"
}

Get Tests¶

This call returns a list of all available Email Tests and some metadata about them. Email Tests are stored for 90 days. The query string is an optional standard URL parameterized version containing any or all of the below search parameters.

GET /v1/preview/tests?<query_string>

The available search query parameters are as follows:

Name	Description
`from`	The starting point of your test date range.
`to`	The ending point of your test date range.
`subject`	The `subject` field of returned tests must contain the exact string. This search is case-insensitive.
`results`	The number of results to return. Must be between 1 and 200. The default value is 50.
`page`	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.

Example response:

[
  {
    "id": "<TEST_ID>",
    "date": 1648177673,
    "type": "email-test",
  },
  {
    "id": "<TEST_ID>",
    "date": 1648177673,
    "type": "email-test",
  }
]

Get Test Info¶

This call returns the subject and submission time in UNIX timestamp format. It will also contain one to three properties containing an array of clients. The completed property shows clients that have completed screenshots uploaded. The processing property contains clients which are still being processed by our system. The bounced property contains clients that were bounced by the destination and cannot be retried.

This call will automatically requeue screenshots if they stay in processing for more than three minutes.

GET /v1/preview/tests/{TEST_ID}

Example response:

{
  "subject": "Test Subject",
  "date": 1470034800,
  "completed": [
    "iphone12_15",
    "iphone12_15_dm"
  ],
  "processing": [
    "iphone13_15"
  ],
  "bounced": [
    "ffr_chr26_win"
  ]
}

Get Test Results¶

This call returns detailed results for screenshots including their upload locations, send times, completion times, and information about bounces, if any. TEST_ID is a test ID returned from test creation or the get tests functions.

The URLs in this call are static – that is to say that they will not change for the duration your test is active (90 days from test creation). Any reprocessing that is done will replace the images in these locations. The image locations are generated programmatically before the screenshots are complete, so the presence of a URL in the call is not a guarantee that the file will be present. Use the “status” property to determine whether or not the file is present in the location, or you can manually test the URL provided. If the file is not present, you will receive a 403 Forbidden response from the endpoint.

GET /v1/preview/tests/{TEST_ID}/results

Example response:

{
  "iphone13_15": {
    "id": "iphone13_15",
    "display_name": "iPhone 13",
    "client": "iPhone",
    "os": "iOS 15",
    "category": "Mobile",
    "screenshots": {
      "default": "<URL>",
      "horizontal": "<URL>"
    },
    "thumbnail": "<URL>",
    "full_thumbnail": "<URL>",
    "status": "Complete",
    "status_details": {
      "submitted": 1649353640,
      "completed": 1649353649
    }
  },
  "iphone13_15_dm": {
    ...
  }
}

Get Test Content¶

Each of these calls will return an object with a single property content that contains the desired format of content. TEST_ID is a test ID returned from test creation or the get tests functions.

Example response:

{
  "content": "<CONTENT>"
}

HTML

This call returns the HTML associated with your Email Test. This is what is sent to our servers.

GET /v1/preview/tests/{TEST_ID}/content

INLINED CSS CONTENT

This call returns HTML with all stylesheets inlined into the HTML.

GET /v1/preview/tests/{TEST_ID}/content/inlinecss

TEXT ONLY CONTENT

This call returns a plain text version of your HTML. This approximates what will be displayed on devices that do not support HTML content. Our system does not currently support multipart emails, so if you send a separate text/plain section when you send your email, this may not be accurate to what users see. Additionally, devices may differ in their plain text renderings, so this function should be used more as a guide than as an exact preview.

GET /v1/preview/tests/{TEST_ID}/content/textonly

Delete Test¶

This call marks an Email Test as deleted. Once it is deleted, it cannot be recovered.

DELETE /v1/preview/tests/{TEST_ID}

Example response:

{
  "success": true
}

Reprocess Screenshots¶

Sometimes strange things happen on the internet. If a strange result has come back in your screenshot, use this function to tell us to retake your screenshot free of charge.

The request should contain an object with a property of clients that contains a list of clients in the TEST_ID provided. The object returned will have a success value indicating if the attempt was successful. If it is false, there will be a reason value describing the failure reason.

PUT /v1/preview/tests/{TEST_ID}/results/reprocess

Example request body:

{
  "clients": [
    "iphone13_15",
    "iphone13_15_dm"
  ]
}

Example response:

{
  "iphone13_15": {
    "success": true,
    "remaining_reprocesses": 19,
    "regional": false,
    "screenshot": {
      "id": "",
      "type": "resubmit",
      "sent": 1649356634,
      "completed": 0
    }
  },
  "iphone13_15_dm": {
    ...
  }
}

Get Clients¶

This call returns a list of available email clients.

The object will contain a clients property, with properties corresponding to the client IDs. Each of these properties will contain an object containing the client ID, a printable client name, and OS. Clients are split into three categories: “Web”, “Application”, and “Mobile”. “Browser” type clients will contain a browser property.

Missing properties should be interpreted as a feature NOT being supported (i.e. equivalent to “false”). The API MAY respond with “false”.

GET /v1/preview/tests/clients

Example response:

{
  "iphone13_15": {
    "id": "iphone13_15",
    "client": "iPhone 13",
    "os": "iOS 15",
    "category": "Mobile",
    "rotate": true,
    "default": true
  },
  ...
}

Response property details:

Field	Description
`id`	Our unique identifier for the email client. This code can be used when creating new Email Tests.
`client`	Name of the email client.
`os`	The name of the OS that this client is running on.
`category`	The type of client this is: one of “Application”, “Mobile”, or “Web”
`browser`	If this is client is in a browser, the name of the browser the client is running in.
`rotate`	A boolean value indicating if this client supports orientation changes. If it is missing, assume `false`.
`default`	A boolean value indicating if this client will be included if no client key is sent with test creation. If it is missing, assume `false`.