Back to Customer API documentation

Customer REST API Method: emails/create

Creates a new email test in your account.

This will create a new email test, there are a two ways to create a new email test.

1. Send your email to Litmus

Using this method, there are a few steps to the process of creating an email test and displaying it to the end user, the advantage is that it is that your email will arrive at Litmus in the same way that it will arrive in your customers inbox, via SMTP.

Create the new email test, specifying the email clients you wish to test it on.
Record the new test's ID, and its GUID.
Send the email that is to be tested, to the address specified in the GUID field.
Poll Litmus on the test's progress. The received field will be set to true when the email has been received by our system.
Once the test is complete, record the URLs to the result screenshots, and present these to your user.

URL:

https://#{company}.litmus.com/emails.xml

HTTP Method(s):

POST

Curl example:

curl -i -X POST -u user:password -H 'Accept: application/xml' -H 'Content-Type: application/xml' https://#{company}.litmus.com/emails.xml -d @data.xml

Parameters:

Request:

XML example:

<?xml version="1.0"?>
<test_set>
  <applications type="array">
    <application>
      <code>hotmail</code>
    </application>
    <application>
      <code>gmail</code>
    </application>
    <application>
      <code>notes8</code>
    </application>
  </applications>
  <save_defaults>false</save_defaults>
  <use_defaults>false</use_defaults>
</test_set>

Response:

XML example (truncated):

<?xml version="1.0" encoding="UTF-8"?>
<test_set>
  <created_at type="datetime">2009-10-05T10:49:52Z</created_at>
  <id type="integer">76425</id>
  <updated_at type="datetime">2009-10-05T10:49:53Z</updated_at>
  <name>No subject</name>
  <service>email</service>
  <state>waiting</state>
  <public_sharing>false</public_sharing>
  <test_set_versions type="array">
    <test_set_version>
      <version type="integer">1</version>
      <url_or_guid>40b1b5f@emailtests.com</url_or_guid>
      <received>false</received>
      <source_url>s3.amazonaws.com/sitevista/missing_source</source_url>
      <inline_css></inline_css>
      <results type="array">
        <result>
          <check_state nil="true"></check_state>
          <error_at type="datetime" nil="true"></error_at>
          <finished_at type="datetime" nil="true"></finished_at>
          <id type="integer">1284887</id>
          <started_at type="datetime" nil="true"></started_at>
          <test_code>hotmail</test_code>
          <state>pending</state>
          <result_type>email</result_type>
          <rendered_html_url></rendered_html_url>
          <testing_application>
            <average_time_to_process type="integer">213</average_time_to_process>
            <business>false</business>
            <result_type>email</result_type>
            <supports_content_blocking>false</supports_content_blocking>
            <desktop_client>false</desktop_client>
            <status>0</status>
            <platform_name>Web-based</platform_name>
            <platform_long_name>Web-based</platform_long_name>
            <application_code>hotmail</application_code>
            <application_long_name>Live Hotmail</application_long_name>
          </testing_application>
          <result_images type="array">
            <result_image>
              <image_type>window_on</image_type>
            </result_image>
            <result_image>
              <image_type>full_on</image_type>
            </result_image>
            <result_image>
              <image_type>window_off</image_type>
            </result_image>
            <result_image>
              <image_type>full_off</image_type>
            </result_image>
          </result_images>
        </result>
        ...
      </results>
    </test_set_version>
    ...
  </test_set_versions>
</test_set>

2. Upload your HTML to Litmus

For this method, you simply supply your email body and subject as part of the XML request to the API. Simply change your request to look like this, everything else remains the same as the example above.

Request:

XML example:

<?xml version="1.0"?>
<test_set>
  <applications type="array">
    <application>
      <code>hotmail</code>
    </application>
    <application>
      <code>gmail</code>
    </application>
    <application>
      <code>notes8</code>
    </application>
  </applications>
  <save_defaults>false</save_defaults>
  <use_defaults>false</use_defaults>
  <email_source>
     <body><![CDATA[your-email-html-goes-here]]></body>
     <subject>My test email to Litmus</subject>
  </email_source>
</test_set>