View and Edit

Blocks

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

You can live test these API endpoints with the “Try It” button for each endpoint on this page.

get

Retrieve a list of Blocks with addresses and response codes, optionally with dates.

URI Parameter Required Requirements Description
date false 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 false If specified, must be an integer greater than 0 Number of days in the past for which to retrieve blocks (includes today)
start_date false 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 false 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 false Must be an integer. Optional field to limit the number of results returned.
offset false Must be an integer. Optional beginning index in the list to retrieve from.

Parameter Value Requirements Description

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
19
20

[
  {
    "status": "4.0.0",
    "created": "2012-09-02 00:12:12",
    "reason": "550 Access denied...04d52d35b93501d500a9bca895ddad5cddd1a9f8486c89ace8c5e959398198cd49cd58288c9d11313975284d852811... (throttled)",
    "email": "[email protected]"
  },
  {
    "status": "4.0.0",
    "created": "2012-09-02 00:21:29",
    "reason": "Connection timed out",
    "email": "[email protected]"
  },
  {
    "status": "4.0.0",
    "created": "2012-09-02 00:25:33",
    "reason": "Unable to resolve MX record for exampledomain.com: nxdomain",
    "email": "[email protected]"
  }
]

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>[email protected]</email>
      <status>5.1.1</status>
      <reason>host [127.0.0.1] said: 550 5.1.1 unknown or illegal user: [email protected]</reason>
      <created>2009-06-10 12:40:30</created>
   </block>
   <block>
      <email>[email protected]</email>
      <status>5.1.1</status>
      <reason>host [127.0.0.1] said: 550 5.1.1 unknown or illegal user: [email protected]</reason>
      <created>2009-08-01 10:16:30</created>
   </block>
</blocks>

delete

Delete an address from the Block list.

URI Parameter Required Requirements Description
email true Must be a valid user account email. Blocked email address to remove.

Parameter Value Requirements Description

Call

POST https://api.sendgrid.com/api/blocks.delete.json
POST Data api_user=your_sendgrid_username&api_key=your_sendgrid_password&email=[email protected]

Response

1
2
3

{
  "message": "success"
}

Call

POST https://api.sendgrid.com/api/blocks.delete.xml
POST Data api_user=your_sendgrid_username&api_key=your_sendgrid_password&email=[email protected]

Response

1
2
3
4

<result>
   <count>4</count>
   @nodes
</result>

count

URI Parameter Required Requirements Description
start_date false Date must be in YYYY-MM-DD format and be before the end_date parameter. Optional date to start counting from.
end_date false Date must be in YYYY-MM-DD format and be after the start_date parameter. Optional date to start counting from.
type false hard or soft The type of bounce to count.
Parameter Value Requirements Description

Call

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

Response

1
2
3

{
  "count": "4"
}

Call

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

Response

1
2
3

<result>
   <count>4</count>
</result>