This endpoint allows you to retrieve and delete entries in the Blocks list.

get

Retrieve a list of Blocks with addresses and response codes, optionally with dates.
Parameter Required Requirements Description
date No Must be set to 1 Retrieve the timestamp of the Block records. It will return a date in a MySQL timestamp format - YYYY-MM-DD HH:MM:SS
days No If specified, must be an integer greater than 0 Number of days in the past for which to retrieve blocks (includes today)
start_date No Date must be in YYYY-MM-DD format and be earlier than the end_date parameter. The start of the date range for which to retrieve blocks.
end_date No Date must be in YYYY-MM-DD format and be later than the start_date parameter. The end of the date range for which to retrieve blocks.
limit No some integer Optional field to limit the number of results returned.
offset No some integer optional beginning point in the list to retrieve from.

Call

GET https://api.sendgrid.com/api/blocks.get.json?api_user=your_sendgrid_username&api_key=your_sendgrid_password&date=1

Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
{
  "status": "4.0.0",
  "created": "2012-09-02 00:12:12",
  "reason": "550 Access denied...04d52d35b93501d500a9bca895ddad5cddd1a9f8486c89ace8c5e959398198cd49cd58288c9d11313975284d852811... (throttled)",
  "email": "example@juno.com"
},
{
  "status": "4.0.0",
  "created": "2012-09-02 00:21:29",
  "reason": "Connection timed out",
  "email": "example2@band.la"
},
{
  "status": "4.0.0",
  "created": "2012-09-02 00:25:33",
  "reason": "Unable to resolve MX record for exampledomain.com: nxdomain",
  "email": "example3@exampledomain.com"
}

Call

GET https://api.sendgrid.com/api/blocks.get.xml?api_user=your_sendgrid_username&api_key=your_sendgrid_password&date=1

Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
<blocks>
   <block>
      <email>email1@domain.com</email>
      <status>5.1.1</status>
      <reason>host [127.0.0.1] said: 550 5.1.1 unknown or illegal user: email1@domain.com</reason>
      <created>2009-06-10 12:40:30</created>
   </block>
   <block>
      <email>email2@domain2.com</email>
      <status>5.1.1</status>
      <reason>host [127.0.0.1] said: 550 5.1.1 unknown or illegal user: email2@domain2.com</reason>
      <created>2009-08-01 10:16:30</created>
   </block>
</blocks>

delete

Delete an address from the Block list.
Parameter Required Requirements Description
email Yes Must be a valid user account email Email block address to remove

Call

POST https://api.sendgrid.com/api/blocks.delete.json
POST Data api_user=your_sendgrid_username&api_key=your_sendgrid_password&email=emailToDelete@domain.com

Response

1
2
3
4
5
6
7
8
9
10
11
12
//success
{
  "message": "success"
}

//error
{
  "message": "error",
  "errors": [
    "...error messages..."
  ]
}

Call

POST https://api.sendgrid.com/api/blocks.delete.xml
POST Data api_user=your_sendgrid_username&api_key=your_sendgrid_password&email=emailToDelete@domain.com

Response

1
2
3
4
5
6
7
8
9
10
<!-- Success -->
<result>
   <count>4</count>
   @nodes
</result>

<!-- Error -->
<result>
   <message>error: reason</message>
</result>

count

Parameter Required Requirements Description
start_date No Date must be in YYYY-mm-dd format and be before the end_date parameter Optional date to start counting from.
end_date No Date must be in YYYY-mm-dd format and be after the start_date parameter Optional date to end counting from.
type No hard or soft choose the type of bounce to search for.

Call

GET https://api.sendgrid.com/api/blocks.count.json?api_user=your_sendgrid_username&api_key=your_sendgrid_password

Response

1
2
3
4
5
6
7
8
9
10
11
12
//success
{
  "count": "4"
}

//error
{
  "message": "error",
  "errors": [
    "...error messages..."
  ]
}

Call

GET https://api.sendgrid.com/api/blocks.count.xml?api_user=your_sendgrid_username&api_key=your_sendgrid_password

Response

1
2
3
4
5
6
7
8
9
10
<?xml version="1.0" encoding="ISO-8859-1"?>
<!-- success -->
<result>
   <count>4</count>
</result>

<!-- error -->
<result>
   <message>error: reason</message>
</result>