return to Table of Contents, API

/projects/:document_identifier/reports/:report_uuid

This resource supports the GET, PATCH, and DELETE methods.

URL Parameters

Label Description
:document_identifier The project's document identifier
:report_uuid The UUID of the report

GET

Returns information about the report.

Request Query String Parameters

Name Required Description
fields No A comma-separated list of the keys you want returned for the report. Default is to return all keys.

Response Status Codes

Code Description
503 Service Unavailable Server is undergoing maintenance and is unavailable
429 Rate Limited Rate limiting in effect, try again later
404 Not Found The resource could not be found or your API key has not been granted access to it
403 Forbidden Direct Mail account is disabled
401 Unauthorized API key, secret, or authentication method is incorrect
200 OK Success

Response Body

A JSON object representing the report.

Note: Reports for campaigns sent with versions of Direct Mail prior to 3.5 will return null for the following keys: number_of_bounced, number_of_opened, number_of_opens, number_of_clicked, number_of_clicks, number_of_spam_complaints, number_of_unsubscribes, number_of_links, and do not contain a rel:links subresource.

Key Value Description
uuid String The UUID of the report
title String The title of the report
is_autoresponder Boolean True if the report is for an autoresponder
delivery_method String e3ds if the campaign was sent via e3 Delivery Service, smtp if the campaign was sent via private SMTP
status String One of waiting, sending, sent, canceled, or error
send_date String The date the email was sent or will be sent, in ISO-8601 format. null if the campaign is a draft without a send date.
notes String User-editable notes
tracking_enabled Boolean True of open and click tracking was enabled for this campaign
web_message_url String URL for the hosted web version of the email
web_report_url String URL for the web report
number_of_bounced Integer The number of bounced emails
number_of_opened Integer The number of recipients that opened the campaign at least once. null if the campaign was sent with tracking turned off.
number_of_opens Integer The total number of opens. null if the campaign was sent with tracking turned off.
number_of_clicked Integer The number of recipients that clicked a link in the campaign at least once. null if the campaign was sent with tracking turned off.
number_of_clicks Integer The total number of clicks. null if the campaign was sent with tracking turned off.
number_of_spam_complaints Integer The number of complaints the campaign has received
number_of_unsubscribes Integer The number of recipients that unsubscribed
number_of_failed Integer The number of recipients that failed to send
number_of_recipients Integer The number of recipients
number_of_links Integer The total number of links in the body of the message. null if the campaign was sent with tracking turned off.
links Array of Object URLs for the report (rel:self), its message (rel:message), recipients (rel:recipients), and links in the message body (rel:links). The rel:links URL will not be included if the campaign was sent with tracking turned off.

Example

GET /api/v2/projects/187812f26ba37d9769d8691d2a83c95c/reports/F4B2E4E6-B94F-462C-AFEC-1F9497BA98A0 HTTP/1.1
Authorization: Basic QzFENDREMjEtNTA4MC00NTM3LUFFOD
Accept: application/json; charset=utf-8
Host: secure.directmailmac.com

HTTP/1.1 200 OK
Date: Thu, 23 Apr 2015 22:57:59 GMT
Content-Type: application/json; charset=utf-8

{
    "delivery_method": "smtp",
    "is_autoresponder": false,
    "links": [
        {
            "href": "https://secure.directmailmac.com/api/v2/projects/187812f26ba37d9769d8691d2a83c95c/reports/F4B2E4E6-B94F-462C-AFEC-1F9497BA98A0",
            "rel": "self"
        },
        {
            "href": "https://secure.directmailmac.com/api/v2/projects/187812f26ba37d9769d8691d2a83c95c/reports/F4B2E4E6-B94F-462C-AFEC-1F9497BA98A0/message",
            "rel": "message"
        },
        {
            "href": "https://secure.directmailmac.com/api/v2/projects/187812f26ba37d9769d8691d2a83c95c/reports/F4B2E4E6-B94F-462C-AFEC-1F9497BA98A0/recipients",
            "rel": "recipients"
        },
        {
            "href": "https://secure.directmailmac.com/api/v2/projects/187812f26ba37d9769d8691d2a83c95c/reports/F4B2E4E6-B94F-462C-AFEC-1F9497BA98A0/recipients?status=bounced",
            "rel": "bounces"
        },
        {
            "href": "https://secure.directmailmac.com/api/v2/projects/187812f26ba37d9769d8691d2a83c95c/reports/F4B2E4E6-B94F-462C-AFEC-1F9497BA98A0/recipients?status=unsubscribed",
            "rel": "unsubscribes"
        },
        {
            "href": "https://secure.directmailmac.com/api/v2/projects/187812f26ba37d9769d8691d2a83c95c/reports/F4B2E4E6-B94F-462C-AFEC-1F9497BA98A0/recipients?status=complained",
            "rel": "spam-complaints"
        },
        {
            "href": "https://secure.directmailmac.com/api/v2/projects/187812f26ba37d9769d8691d2a83c95c/reports/F4B2E4E6-B94F-462C-AFEC-1F9497BA98A0/recipients?status=failed",
            "rel": "errors"
        },
        {
            "href": "https://secure.directmailmac.com/api/v2/projects/187812f26ba37d9769d8691d2a83c95c/reports/F4B2E4E6-B94F-462C-AFEC-1F9497BA98A0/links",
            "rel": "links"
        }
    ],
    "notes": null,
    "number_of_bounced": 0,
    "number_of_clicked": 397,
    "number_of_clicks": 397,
    "number_of_failed": 0,
    "number_of_links": 2,
    "number_of_opened": 657,
    "number_of_opens": 792,
    "number_of_recipients": 758,
    "number_of_spam_complaints": 0,
    "number_of_unsubscribes": 0,
    "send_date": "2015-04-23T22:53:48+0000",
    "status": "sent",
    "title": "This is a test email",
    "tracking_enabled": true,
    "uuid": "F4B2E4E6-B94F-462C-AFEC-1F9497BA98A0",
    "web_message_url": "https://dmanalytics1.com/campaign?d=R2mIj9vGR9WKzA7t4ZYZGQ&t=1",
    "web_report_url": null
}

PATCH

Updates the user-editable properties of the report.

Request Body

A JSON object representing the properties you want to update. You may update the following keys:

Key Required Value Description
title No String The title of the report
notes No String The user-editable notes

Response Status Codes

Code Description
503 Service Unavailable Server is undergoing maintenance and is unavailable
429 Rate Limited Rate limiting in effect, try again later
404 Not Found The project could not be found
403 Forbidden Direct Mail account is disabled or the report is not editable
401 Unauthorized API key, secret, or authentication method is incorrect
400 Bad Request One or more of the values in the request body is invalid
202 Accepted The request has been accepted for processing

Response Body

A JSON object representing the merge task.

Key Value Description
links Array of Object URLs for the merge task and the updated resource.

Example

PATCH /api/v2/projects/187812f26ba37d9769d8691d2a83c95c/reports/F4B2E4E6-B94F-462C-AFEC-1F9497BA98A0 HTTP/1.1
Authorization: Basic QzFENDREMjEtNTA4MC00NTM3LUFFOD
Content-Type: application/json; charset=utf-8
Host: secure.directmailmac.com
Content-Length: 50

{
    "notes": "These are some notes added via the API"
}

HTTP/1.1 202 Accepted
Date: Thu, 23 Apr 2015 22:59:41 GMT
Content-Type: application/json; charset=utf-8

{
    "links": [
        {
            "href": "https://secure.directmailmac.com/api/v2/projects/187812f26ba37d9769d8691d2a83c95c/merge-task?s=67&m=PATCH&r=https%3A%2F%2Fsecure.directmailmac.com%2Fapi%2Fv2%2Fprojects%2F187812f26ba37d9769d8691d2a83c95c%2Freports%2FF4B2E4E6-B94F-462C-AFEC-1F9497BA98A0",
            "rel": "merge-task"
        },
        {
            "href": "https://secure.directmailmac.com/api/v2/projects/187812f26ba37d9769d8691d2a83c95c/reports/F4B2E4E6-B94F-462C-AFEC-1F9497BA98A0",
            "rel": "resource"
        }
    ]
}

DELETE

Deletes the report. Reports for campaigns that are waiting to be sent, are currently sending, or are associated with an autoresponder cannot be deleted.

Response Status Codes

Code Description
503 Service Unavailable Server is undergoing maintenance and is unavailable
429 Rate Limited Rate limiting in effect, try again later
404 Not Found The project could not be found
403 Forbidden Direct Mail account is disabled or the report is not editable
401 Unauthorized API key, secret, or authentication method is incorrect
400 Bad Request One or more of the values in the request body is invalid
202 Accepted The request has been accepted for processing

Response Body

A JSON object representing the merge task.

Key Value Description
links Array of Object URL for the merge task.

Example

DELETE /api/v2/projects/187812f26ba37d9769d8691d2a83c95c/reports/F4B2E4E6-B94F-462C-AFEC-1F9497BA98A0 HTTP/1.1
Authorization: Basic QzFENDREMjEtNTA4MC00NTM3LUFFOD
Host: secure.directmailmac.com

HTTP/1.1 202 Accepted
Date: Thu, 23 Apr 2015 23:44:21 GMT
Content-Type: application/json; charset=utf-8

{
    "links": [
        {
            "href": "https://secure.directmailmac.com/api/v2/projects/187812f26ba37d9769d8691d2a83c95c/merge-task?s=68&m=DELETE&r=https%3A%2F%2Fsecure.directmailmac.com%2Fapi%2Fv2%2Fprojects%2F187812f26ba37d9769d8691d2a83c95c%2Freports%2FF4B2E4E6-B94F-462C-AFEC-1F9497BA98A0",
            "rel": "merge-task"
        }
    ]
}

Did you find this article helpful? Yes | No