Retrieve metrics from your Dyn Delivery accounts using the API.

REST Methods

NOTE: API is case sensitive. Make all parameters entries lower case. All parameters in red are required. It is best to provide either a sender_id or user_id in your query, when applicable, even though these may not be required parameters.

NOTE: Metrics for Opens, Clicks, Complaints and sending Issues must still be called from the older Email Delivery API.

 

VERB RESOURCE PARAMETERS DESCRIPTION
GET /bounces
  • start_time
  • end_time
  • user_id
  • sender or (sender_id)
  • xheaders
  • offset
  • domain
  • local
  • recipient
  • bounce_type
  • bounce_category
Returns a list of all email bounces received for the specified account and date range, optionally filtered by sender.
GET /bounce/[user_id]/[sender_id]/[bounce_time]/[email_id]
  • user_id
  • sender_id
  • bounce_time
  • email_id
Retrieves comprehensive data on the specified bounce
GET /bounce/counts
  • start_time
  • end_time
  • user_id
  • sender_id
  • rollup_to
  • timeseries
  • bounce_type
Retrieve aggregate soft and hard bounce counts for a specified user or sender.
GET /bounce/categories None. Retrieves a list of all current bounce categories.
GET /emails
  • start_time
  • end_time
  • user_id
  • sender (or sender_id)
  • xheaders
  • offset
  • domain
  • local
  • recipient
  • delivered
Retrieves emails matching the filters for the given user_id.
GET /email/counts
  • start_time
  • end_time
  • user_id
  • sender_id
  • rollup_to
  • timeseries
Returns the total number of emails sent through the specified account within the specified date range, optionally filtered by sender.
GET /blocked-emails
  • start_time
  • end_time
  • user_id
  • sender or (sender_id)
  • xheaders
  • offset
  • domain
  • local
  • recipient
  • blocked_reason
Returns a list of all emails that were blocked from sending due to a suppressed recipient.
GET /blocked-email/counts
  • start_time
  • end_time
  • user_id
  • sender_id
  • rollup_to
  • timeseries
Retrieve aggregate blocked email counts for a specified user, or sender.
GET /blocked-email/reasons None Retrieves a list of all current blocked email reasons.

 


GET /bounces

Retrieves a list of up to 500 bounces at a time. To retrieve bounces over the initial 500, the offset can be used.

Parameters

  • start_timeRequired. Start date/time range as a unix timestamp or full ISO 8601 format.
  • end_timeRequired. Start date/time range as a unix timestamp or full ISO 8601 format
  • user_id — The user ID.
  • sender (or sender_id) — The full approved sender email address or ID of the sender.
  • xheaders — Specify up to four custom x-headers as X-[header name]=value.
  • offset — A positive integer indicating the starting index of where to begin the list of bounces. The first 500 are returned when offset is omitted.
  • domain — The domain part of the recipient(s) email address.
  • local — The local part of a recipient email address.
  • recipient — The specific recipient email address
  • bounce_type — The bounce type either bounce_type=hard or bounce_type=soft
  • bounce_category — Any of the bounce categories which can be retrieved using the GET bounce/categories.
    • bad-configuration – A configuration problem at the receiving email provider caused delivery to fail.
    • bad-connection – Indicates a connection could not be successfully made to the receiving server.
    • bad-domain – The recipient domain was not recognized.
    • bad-mailbox – Non-existent recipient.
    • content-related – Indicates email content has been classified as spam by the receiving email provider.
    • inactive-mailbox – The recipient mailbox is currently inactive or has been disabled.
    • invalid-sender – The email sender was recognized as invalid.
    • message-expired – The email has exceeded its expiration date.
    • no-answer-from-host – There was no response by the receiving email provider.
    • blockedcontent – Indicates email content has been classified as spam by the receiving email provider.
    • content-related – Total message size, including headers, exceeds the receiving email provider’s allowed maximum message size or other content related issue.
    • other – The email was not successfully delivered for a reason other than the common classifications listed.
    • policy-related – Indicates email has been classified as spam by the receiving email provider.
    • protocol-errors – There were protocol errors in communication with the receiving email provider.
    • quota-issues – Recipient mailbox is full or recipient’s quota has been exceeded.
    • relaying-issues – Error in transmission between Dyn and the email provider.
    • routing-errors – The email was not delivered due to errors in routing to the receiving email provider.
    • spam-related – Email has been classified as spam by the receiving email provider.
    • unclassified – The email has not been able to be classified by Dyn’s system.
    • virus-related – The receiving email provider has detected a virus within the email.

    Example Results (JSON)

    [
       {
          "domain":"example.com",
          "bounce_category":"policy-related",
          "email_id":"20161122000000.125874958762@mail6-40-ussnn1",
          "postback_time":0,
          "bounce_time":1479772800,
          "sender_id":17,
          "bounce_type":"soft",
          "email_address":"recipient1@example.com",
          "user_id":21,
          "xheaders":{
             "X-Subscription11":"None",
             "X-CampaignMaster11":"Notification",
             "X-DistrictMaster11":"New Hampshire",
             "X-OptIn11":"Refused"
          },
          "bounce_code":"4.2.0",
          "process_time":1479772800,
          "local":"recipient1"
       }
    ]

    GET /bounce/[user_id]/[sender_id]/[bounce_timestamp]/[email_id]

    Retrieves the detail bounce data for a given bounce email including full bounce email content.

    The user_id, sender_id, email_id, and bounce_time can be found in the relevant record from the data set returned from a GET /bounces request.

    Parameters:
    NOTE: All four parameters, in correct order, are required.

    • user_idRequired. The user ID sending that sent the email.
    • sender_idRequired. The sender ID.
    • bounce_timeRequired. The bounce timestamp.
    • email_idRequired. The email id of the bounce.

    Example Results (JSON):

    {
        "processing_time": 0.2052,
        "resp_time": 1477422244.8282,
        "data": {
            "domain": "example.com",
            "bounce_category": "policy-related",
            "xheaders": [
                "X-Subscription11": "None",
                "X-CampaignMaster11": "Notification",
                "X-DistrictMaster11": "New Hampshire",
                "X-OptIn11": "Refused"
            ],
            "bounce_code": "5.2.2",
            "email_id": "20160829200233.000004d57a76@mail6-45-ussnn1",
            "process_time": 1472500953,
            "sender_id": 107546,
            "local": "recipient1",
            "bounce_type": "soft",
            "full_content": "Return-Path: <>\nX-Original-To: bounces+miiakarppanen=luukku.com@dynrp.wish.com\nDelivered-To:  
                bounces+tester2=recipient1@example.com.testapi.com\nReceived: from mtaout-04013-pao.dynect.net
                (unknown [162.88.4.13])\n\tby bounce6-02-pao.dyndns.com (Postfix) with ESMTPS id 90E4B1FE51\n\t
                [full bounce email is provided - truncated here for convenience]",
            "bounce_time": 1472500955,
            "diagnostic_code": "smtp;552 5.2.2 <recipient1@example.com>: Recipient address rejected: Over quota",
            "user_id": 405954,
            "regex_name": "policyrelated03",
            "email_address": "recipient1@example.com",
            "postback_time": 0
        },
        "api_host": "testapi.com",
        "recv_time": 1477422244.623
    }

    GET /bounce/counts

    Retrieves hard and soft bounce counts for a given hourly or daily time range.

    Parameters

    • start_timeRequired. Start date/time range as a unix timestamp or full ISO 8601 format.
    • end_timeRequired. Start date/time range as a unix timestamp or full ISO 8601 format
    • user_id — The user ID.
    • sender_id — The sender ID.
    • rollup_to – When used, this parameter will provide an aggregation of counts by the specific value. Valid values are rollup_to=user or rollup_to=sender. Defaults to sender.
    • timeseries – produces a time series output for a given time period, aggregated by hour or day. Valid values are timeseries=day or timeseries=hour.
    • bounce_type — The bounce type either bounce_type=hard or bounce_type=soft



    Example Results (JSON)

    {
       "processing_time":1.1909,
       "resp_time":1483459119.2615,
       "data":[
          {
             "bounce_count":13536,
             "sender_id":17,
             "sender":"v4master1sub1sender1@dyn.com",
             "soft_bounce_count":9024,
             "hard_bounce_count":4512
          },
          {
             "bounce_count":13536,
             "sender_id":18,
             "sender":"v4master1sub1sender2@dyn.com",
             "soft_bounce_count":9024,
             "hard_bounce_count":4512
          }
       ]
    }
    



    Example Results (JSON) with timeseries = day

    {
       "19":[
          {
             "bounce_count":0,
             "timestamp":1479600000,
             "soft_bounce_count":36096,
             "hard_bounce_count":13092
          },
          {
             "bounce_count":0,
             "timestamp":1479686400,
             "soft_bounce_count":76056,
             "hard_bounce_count":10094
          },
          {
             "bounce_count":0,
             "timestamp":1479772800,
             "soft_bounce_count":98076,
             "hard_bounce_count":10001
          }
       ]
    }
    

    GET /bounce/categories

    Retrieves a list of the current bounce categories.

    Parameters:
    None.

    Example Results (JSON):

    {
       "data":[
          "bad-configuration",
          "bad-connection",
          "bad-domain",
          "bad-mailbox",
          "content-related",
          "inactive-mailbox",
          "invalid-sender",
          "message-expired",
          "no-answer-from-host",
          "other",
          "policy-related",
          "protocol-errors",
          "quota-issues",
          "relaying-issues",
          "routing-errors",
          "spam-related",
          "unclassified",
          "virus-related"
       ]
    }
    

    GET /emails

    Retrieves a list of up to 500 sent emails at a time. To retrieve sent emails over the initial 500, the offset can be used. A listing of delivered emails can be retrieved by setting the parameter delivered = 1 (true)

    Parameters

    • start_timeRequired. Start date/time range as a unix timestamp or full ISO 8601 format.
    • end_timeRequired. Start date/time range as a unix timestamp or full ISO 8601 format
    • user_id – The user id.
    • sender (or sender_id) – the full approved sender email address (or ID of the sender).
    • xheaders – Specify up to four X-=value.
    • offset – A positive integer indicating the starting index of where to begin the list of emails. The first 500 are returned when offset is omitted.
    • domain – the domain part of the recipient(s) email address.
    • local – the local part of a recipient email address.
    • recipient – the specific recipient email address.
    • delivered – setting delivered=1 will retrieve all delivered emails. Omitting the delivered parameter will retrieve all emails sent, including undelivered emails such as those that have bounced, or been blocked from sending due to suppressed recipients.
    {
       "data":[
          {
             "email_address":"recipient3@yahoo.com",
             "domain":"yahoo.com",
             "user_id":20,
             "xheaders":[
                "X-Subscription11":"Monthly",
                "X-CampaignMaster11":"Notification",
                "X-DistrictMaster11":"New Hampshire",
                "X-OptIn11":"Agreed"
             ],
             "delivered":true,
             "email_id":"20161122000000.119152799365@mail6-40-ussnn1",
             "process_time":1479772800,
             "sender_id":23,
             "local":"recipient3"
          },
          {
             "email_address":"recipient2@gmail.com",
             "domain":"gmail.com",
             "user_id":20,
             "xheaders":[
                "X-Subscription11":"Monthly",
                "X-CampaignMaster11":"Notification",
                "X-DistrictMaster11":"North Carolina",
                "X-OptIn11":"Refused"
             ],
             "delivered":true,
             "email_id":"20161122000000.174475085064@mail6-40-ussnn1",
             "process_time":1479772800,
             "sender_id":23,
             "local":"recipient2"
          }
       ]
    }

    GET /email/counts

    Retrieves total email counts for a given hourly or daily time range.

    Parameters

    • start_timeRequired. Start date/time range as a unix timestamp or full ISO 8601 format.
    • end_timeRequired. Start date/time range as a unix timestamp or full ISO 8601 format
    • user_id – The user id.
    • sender_id – The sender id.
    • rollup_to – When used, this parameter will provide an aggregation of counts by the specific value. Valid values are rollup_to=user or rollup_to=sender. Defaults to sender.
    • timeseries – produces a time series output for a given time period, aggregated by hour or day. Valid values are timeseries=day or timeseries=hour.

    Example Results (JSON)

    {
       "data":[
          {
             "sender_id":23,
             "sent_count":4500,
             "sender":"v4master2sub2sender1@dyn.com"
          },
          {
             "sender_id":24,
             "sent_count":4500,
             "sender":"v4master2sub2sender2@dyn.com"
          }
       ]
    }



    Example Results (JSON) with rollup_to = user

    {
       "data":[
          {
             "user_id":20,
             "sent_count":9000
          }
       ]
    }



    Example Results (JSON) with timeseries = hour and rollup_to=user

    {
       "data":{
          "20":[
             {
                "timestamp":1479772800,
                "sent_count":24
             },
             {
                "timestamp":1479776400,
                "sent_count":48
             },
             {
                "timestamp":1479780000,
                "sent_count":48
             }
          ]
       }
    }

    GET /blocked-emails

    Retrieves a list of up to 500 blocked emails at a time. To retrieve blocked emails over the initial 500, the offset can be used.

    Parameters

    • start_timeRequired. Start date/time range as a unix timestamp or full ISO 8601 format.
    • end_timeRequired. Start date/time range as a unix timestamp or full ISO 8601 format
    • user_id – The user ID.
    • sender (or sender_id) – The full approved sender email address (or ID of the sender).
    • xheaders – Specify up to four x-headers as X-=value
    • offset – A positive integer indicating the starting index of where to begin the list of blocked emails. The first 500 are returned when offset is omitted.
    • domain – the domain part of the recipient(s) email address.
    • local – the local part of a recipient email address.
    • recipient – the specific recipient email address.
    • blocked_reason – Any of the blocked reasons which can be retrieved using the GET blocked/reasons.
      • complaint – Recipient suppressed due to a previous complaint.
      • hardbounce – Recipient suppressed due to previous hard bounce.
      • manual – Recipient manually added to suppression list.
      • softbounce – Recipient suppressed due to multiple soft bounces.
      • unsubscribe – Recipient suppressed due to a unsubscribe request.

    Example Results (JSON)

    {
       "data":[
          {
             "email_address":"recipient1@example.com",
             "postback_time":0,
             "user_id":20,
             "xheaders":null,
             "domain":"example.com",
             "email_id":"20161122000000.102802739903@mail6-40-ussnn1",
             "process_time":1479772800,
             "sender_id":23,
             "blocked_reason":"unsubscribe",
             "local":"recipient1"
          },
          {
             "email_address":"recipient3@yahoo.com",
             "postback_time":0,
             "user_id":20,
             "xheaders":null,
             "domain":"yahoo.com",
             "email_id":"20161122000000.103538826002@mail6-40-ussnn1",
             "process_time":1479772800,
             "sender_id":23,
             "blocked_reason":"manual",
             "local":"recipient3"
          }
       ]
    }
    

    GET /blocked-email/counts

    Retrieves total blocked-email counts for a given hourly or daily time range.

    Parameters

    • start_timeRequired. Start date/time range as a unix timestamp or full ISO 8601 format.
    • end_timeRequired. Start date/time range as a unix timestamp or full ISO 8601 format
    • user_id – The user id.
    • sender_id – The sender ID.
    • rollup_to – When used, this parameter will provide an aggregation of counts by the specific value. Valid values are rollup_to=user or rollup_to=sender. Defaults to sender.
    • timeseries – produces a time series output for a given time period, aggregated by hour or day. Valid values are timeseries=day or timeseries=hour.

    Example Results (JSON)

    {
       "processing_time":1.1909,
       "resp_time":1483459119.2615,
       "data":[
          {
             "bounce_count":13536,
             "sender_id":17,
             "sender":"v4master1sub1sender1@dyn.com",
             "soft_bounce_count":9024,
             "hard_bounce_count":4512
          },
          {
             "bounce_count":13536,
             "sender_id":18,
             "sender":"v4master1sub1sender2@dyn.com",
             "soft_bounce_count":9024,
             "hard_bounce_count":4512
          }
       ]
    }
    



    Example Results (JSON) with rollup_to = user

    {
       "data":[
          {
             "user_id":21,
             "blocked_email_count":36096
          },
          {
             "user_id":22,
             "blocked_email_count":36096
          },
          {
             "user_id":20,
             "blocked_email_count":36096
          },
          {
             "user_id":23,
             "blocked_email_count":36096
          },
          {
             "user_id":24,
             "blocked_email_count":36096
          }
       ]
    }



    Example Results (JSON) with timeseries = day and rollup_to=user

    {
       "data":{
          "24":[
             {
                "timestamp":1479600000,
                "blocked_email_count":2345
             },
             {
                "timestamp":1479686400,
                "blocked_email_count":1357
             },
             {
                "timestamp":1479772800,
                "blocked_email_count":900
             }
          ]      "20":[
             {
                "timestamp":1479600000,
                "blocked_email_count":3168
             },
             {
                "timestamp":1479686400,
                "blocked_email_count":4199
             },
             {
                "timestamp":1479772800,
                "blocked_email_count":2333
             }
          ]
       }
    }

    GET /blocked-email/reasons

    Retrieves a list of the current blocked email reasons.

    Parameters:
    None.

    Example Results (JSON)

    {
       "data":[
          "complaint",
          "hardbounce",
          "manual",
          "softbounce",
          "unsubscribe"
       ]
    }