Getting Started | Direct Mail

You can use the Direct Mail API to retrieve, insert, and edit messages, address groups, and campaign reports stored in your Direct Mail projects. Our API is accessed over the Internet by issuing HTTP requests to our servers (see the REST section below). The Direct Mail application does not need to be open or running on your Mac in order for the API to function. Changes made via the API are automatically synced to your Mac or iOS device. There is no charge to use the API.

Please carefully read the following information before using our API. You may contact our support team with any questions, however please note that we do not provide code-level debugging services.

Prerequisites

Direct Mail Account

You must have a Direct Mail account to use the API. If you do not currently have a Direct Mail account but would like to test or develop against our API, you can sign up for a free collaborator account inside the Direct Mail app (choose Direct Mail > Direct Mail Account from the menu bar).

API Key

You will need a Direct Mail API key in order to authenticate yourself to the API. You can obtain a key (and revoke old keys) via your Direct Mail account control panel:

Choose Direct Mail > Direct Mail Account from the menu bar at the top of the screen
Scroll down to the API Access section and click Show
If you don’t already have a key, click the Add New API Key button

The “Key Secret” portion of your key should always be kept private in order to prevent unauthorized access to your Direct Mail data. If your key is ever compromised, we advise revoking it as soon as possible.

Move Project to the Cloud

The Direct Mail API works only with projects that have been moved to the cloud. Click here to learn more about moving your project to the cloud.

Document Identifier

In order to access the data from your Direct Mail project, you will need to know the project’s document identifier. Here’s how to find the document identifier for your Direct Mail project.

Using Direct Mail, open the project
Choose File > Share from the menu bar at the top of the screen (or use the popup menu in the titlebar of the window)
Choose API > Copy Document Identifier from the API popup menu in the bottom left corner of the window

Authorization

Knowledge of the API Key, Key Secret, and the Document Identifier is not enough to gain access to project data. The owner of the Direct Mail project must also explicitly grant your API key access to the project. Here’s how:

Using Direct Mail, open the project
Choose File > Share from the menu bar at the top of the screen (or use the popup menu in the titlebar of the window)
Using the API popup in the bottom-left of the window, select which API keys you want to grant access to
Click OK

REST

Resources

The Direct Mail API is built using REST principles. The API exposes the following resources from your Direct Mail project:

Projects
- Messages
  - Headers
  - Attachments
- Address Groups
  - Addresses
- Reports
  - Message
  - Recipients
    - Opens
    - Clicks
  - Links
    - Clicks

A full list of all the resources available via the API can be found in the API table of contents.

Resources are accessed via the resource's URL, and always over HTTPS. Each URL begins with the following:

https://secure.directmailmac.com/api/v2/

For example:

https://secure.directmailmac.com/api/v2/projects https://secure.directmailmac.com/api/v2/projects/187812f26ba37d9769d8691d2a83c95c https://secure.directmailmac.com/api/v2/projects/187812f26ba37d9769d8691d2a83c95c/reports

Note: If your HTTP library does not support Server Name Indication (SNI), you can also access the API using the hostname www.ethreemail.com.

HTTP Verbs and Status Codes

HTTP requests to the API should use the GET, POST, PATCH, and DELETE HTTP verbs to retrieve, create, update, and delete resources. Responses from the API use HTTP status codes to indicate the success or failure or an API call. For example:

200 OK
201 Created
202 Accepted
204 No Content
400 Bad Request
404 Not Found
etc.

Error responses will also include the status code and error message in the body of the response, JSON formatted as follows:

{
    "code": 404,
    "error_message": "The document was not found."
}

The documentation for each REST resource specifies which error codes you should be prepared to handle.

Data Format

All responses from the API are formatted using JSON with UTF-8 text encoding (Content-Type: application/json; charset=utf-8). POST and PATCH requests to the API should also be formatted using UTF-8 JSON.

Self-Documenting

The API is designed to be as self-documenting as possible and follows HATEOAS principles. Most responses from the API contain a links key whose value is an array with URLs of related resources. For example, here is a sample request and response for a project resource showing links to the messages, address groups, reports, and webhooks sub-resources:

GET /api/v2/projects/187812f26ba37d9769d8691d2a83c95c HTTP/1.1
Authorization: Basic QzFENDREMjEtNTA4MC00NTM3LUFFOD
Accept: application/json; charset=utf-8
Host: secure.directmailmac.com

HTTP/1.1 200 OK
Date: Wed, 22 Apr 2015 17:03:31 GMT
Content-Type: application/json; charset=utf-8

{
    "document_identifier": "187812f26ba37d9769d8691d2a83c95c",
    "name": "API Test Project",
    "address_custom_column_names": [
        "Custom 1",
        "Custom 2",
        "Custom 3",
        "Custom 4",
        "Custom 5",
        "Custom 6",
        "Custom 7",
        "Custom 8",
        "Custom 9",
        "Custom 10",
        "Custom 11",
        "Custom 12",
        "Custom 13",
        "Custom 14",
        "Custom 15"
    ],
    "number_of_messages": 17,
    "number_of_address_groups": 3,
    "number_of_reports": 6,
    "number_of_webhooks": 5,
    "links": [
        {
            "href": "https://secure.directmailmac.com/api/v2/projects/187812f26ba37d9769d8691d2a83c95c/messages",
            "rel": "messages"
        },
        {
            "href": "https://secure.directmailmac.com/api/v2/projects/187812f26ba37d9769d8691d2a83c95c/address-groups",
            "rel": "address-groups"
        },
        {
            "href": "https://secure.directmailmac.com/api/v2/projects/187812f26ba37d9769d8691d2a83c95c/reports",
            "rel": "reports"
        }
        {
            "href": "https://secure.directmailmac.com/api/v2/projects/187812f26ba37d9769d8691d2a83c95c/webhooks",
            "rel": "webhooks"
        }
    ],
    "locale_identifier": "en_US",
    "time_zone_name": "America/Los_Angeles"
}

Authentication and Authorization

Authentication

Each call to the API must be authenticated using HTTP Basic authentication. HTTP Basic authentication requires a username and a password. When accessing the API, your API Key ID is the username and the corresponding Key Secret is the password. For example, if your API Key ID was 57B8CC9F-B0AF-4C18-A50C-BBA75442AED3 and your Key Secret was b4a353b6ea861f6b2e4ff3c0cc5a0172, then you would authenticate each API call by adding the following header to your HTTP request:

Authorization: Basic NTdCOENDOUYtQjBBRi00QzE4LUE1MEMtQkJBNzU0NDJBRUQzOmI0YTM1M2I2ZWE4NjFmNmIyZTRmZjNjMGNjNWEwMTcyCg==

See Prerequisites above for information about API keys.

Authorization

Authentication alone is not enough to grant you access to a Direct Mail project’s data. As mentioned above, the owner of the project must also grant your API key access to the project. Here’s how:

Using Direct Mail, open the project
Choose File > Share from the menu bar at the top of the screen (or use the popup menu in the titlebar of the window)
Using the API popup in the bottom-left of the window, select which API keys you want to grant access to
Click OK

Only API keys belonging to the project’s owner will be listed (or API keys belonging to a previous owner of the project). API clients will have full read and write access to the project.

Rate Limiting

In order to ensure excellent performance for all our users, we may impose rate limits on your API calls. The limits are dynamic and generous, so, in practice, you will likely never be throttled. However, your code should be prepared to handle rate-limiting error responses. If your request is denied due to rate limiting, you will receive HTTP status code 429 in response. Please retry your request using an exponential back-off algorithm until you no longer receive status code 429.

Pagination

Some resources may contain especially large result sets. For example, an address group may contains tens of thousands of addresses. GET requests for these resources do not return the entire result set, but return one "page" of results at a time. You can retrieve the entire result set by requesting consecutive pages.

To determine if a resource supports pagination, please consult the description for the resource's GET method.

To request a particular page of results, use the "page" query string parameter. Page numbers start at 1. If no particular page is requested, the first page of results is returned. Here is an example URL for the 2nd page of addresses:

https://secure.directmailmac.com/api/v2/projects/b003d7bd74ea7c67ddf5a8941b510a90/address-groups/10201B3B-8731-4D39-9116-AFB660DE6D4F/addresses?page=2

Paginated result sets include two extra response headers: X-Page-Limit and Link.

"X-Page-Limit" Header

This header is an integer that indicates the maximum number of results that will appear on any page.

"Link" Header

This header provides a comma-separated list of links to the first, last, previous, and next pages of results. For example:

Links: <https://secure.directmailmac.com/api/v2/projects/b003d7bd74ea7c67ddf5a8941b510a90/address-groups/4F8956D5-03B4-473F-AD43-A818E148E89E/addresses?page=1>; rel="first", <https://secure.directmailmac.com/api/v2/projects/b003d7bd74ea7c67ddf5a8941b510a90/address-groups/4F8956D5-03B4-473F-AD43-A818E148E89E/addresses?page=75>; rel="last", <https://secure.directmailmac.com/api/v2/projects/b003d7bd74ea7c67ddf5a8941b510a90/address-groups/4F8956D5-03B4-473F-AD43-A818E148E89E/addresses?page=2>; rel="next"

Possible rel values are as follows:

Relation	Description
first	The URL of the first page of results
last	The URL of the last page of results
next	The URL of the next page of results. Not included if the current page is the last page.
prev	The URL of the previous page of results. Not included if the current page is the first page.

Asynchronous Inserts, Updates, and Deletes

One unique feature of our API is that inserts, updates, and deletes are performed asynchronously (except for webhooks—see note below). What this means is that POST, PATCH, and DELETE requests always return a response right away, even before the project has actually been modified. Behind the scenes, the body of your request is placed in a queue and merged into the project in the order received at a later time (usually only a few milliseconds). In practice, the merging process usually completes near instantaneously, but that is not guaranteed.

POST, PATCH, and DELETE requests return a special kind of response. If your request is accepted, you will receive an HTTP status code "202 Accepted" response. The body of that response is a dictionary with one key: links. The value for the links key is an array of URLs. For example, here is a POST request to create a new message, and the response from the API:

POST /api/v2/projects/187812f26ba37d9769d8691d2a83c95c/messages HTTP/1.1
Authorization: Basic QzFENDREMjEtNTA4MC00NTM3LUFFOD
Content-Type: application/json; charset=utf-8
Host: secure.directmailmac.com
Content-Length: 194

{
    "content_type": "text/html",
    "from_email": "api-test@example.com",
    "from_name": "Joe User",
    "html_content": "<html><body>This is a test</body></html>",
    "subject": "Hello World!",
    "title": "My Newsletter"
}

HTTP/1.1 202 Accepted
Date: Wed, 22 Apr 2015 18:07:37 GMT
Content-Type: application/json; charset=utf-8

{
    "links": [
        {
            "href": "https://secure.directmailmac.com/api/v2/projects/187812f26ba37d9769d8691d2a83c95c/merge-task?s=18&m=POST&r=https%3A%2F%2Fsecure.directmailmac.com%2Fapi%2Fv2%2Fprojects%2F187812f26ba37d9769d8691d2a83c95c%2Fmessages%2F88EFF66F-5DC0-4290-930A-01365DDE448A",
            "rel": "merge-task"
        },
        {
            "href": "https://secure.directmailmac.com/api/v2/projects/187812f26ba37d9769d8691d2a83c95c/messages/88EFF66F-5DC0-4290-930A-01365DDE448A",
            "rel": "resource"
        }
    ]
}

For POST and PATCH requests, the links array will contain the URL of the resource that you just created or updated. You can use this URL for subsequent requests, if necessary.

The links array also contains a “merge-task” URL. If you are interested in knowing when the changes you requested are actually merged into the project, you can issue GET requests against the “merge-task” URL. Here is how to interpret the responses to those requests:

Status Code	Description
200 OK	The request changes are still waiting to be merged into the project
201 Created	The resource you POSTed has been created. This response will also include a `Location:` header with the URL of the inserted resource.
204 No Content	The resource you PATCHed or DELETEd has been updated or deleted, respectively. This response will also include a `Content-Location:` header with the URL of the PATCHed resource (if applicable)

Inserting and Deleting Webhooks

API requests to create and delete webhooks are performed synchronously. Please see the webhook API documentation for more information about the responses to POST and DELETE requests.

Compression

To receive compressed responses from the server, include the Accept-Encoding: gzip header in your requests.

Development and Debugging Tips

Paw

Paw is a handy macOS app for interacting with REST services. You can use Paw for building HTTP requests, sending requests to the Direct Mail API, and inspecting responses from the API. It is a convenient and friendly way to get started exploring our API.

Feedback Welcome!

We welcome your feedback on any aspect of the API! We look forward to adding additional functionality as we go forward, but will maintain backwards compatibility through the use of semantic versioning.

Stay Up to Date

For technical news and updates specific to the Direct Mail API, please subscribe to our API updates mailing list.

Prerequisites

Direct Mail Account

API Key

Move Project to the Cloud

Document Identifier

Authorization

REST

Resources

HTTP Verbs and Status Codes

Data Format

Self-Documenting

Authentication and Authorization

Authentication

Authorization

Rate Limiting

Pagination

"X-Page-Limit" Header

"Link" Header

Asynchronous Inserts, Updates, and Deletes

Inserting and Deleting Webhooks

Compression

Development and Debugging Tips

Paw

Feedback Welcome!

Stay Up to Date

Why Wait? Direct Mail is free to try!