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_id – Required. The user ID sending that sent the email.sender_id – Required. The sender ID.bounce_time – Required. The bounce timestamp.email_id – Required. 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_time — Required. Start date/time range as a unix timestamp or full ISO 8601 format.end_time — Required. Start date/time range as a unix timestamp or full ISO 8601 formatuser_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_time — Required. Start date/time range as a unix timestamp or full ISO 8601 format.end_time — Required. Start date/time range as a unix timestamp or full ISO 8601 formatuser_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_time — Required. Start date/time range as a unix timestamp or full ISO 8601 format.end_time — Required. Start date/time range as a unix timestamp or full ISO 8601 formatuser_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_time — Required. Start date/time range as a unix timestamp or full ISO 8601 format.end_time — Required. Start date/time range as a unix timestamp or full ISO 8601 formatuser_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-=valueoffset – 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_time — Required. Start date/time range as a unix timestamp or full ISO 8601 format.end_time — Required. Start date/time range as a unix timestamp or full ISO 8601 formatuser_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"
]
}
