Menu

Expand

This documentation is for the SendGrid Web API v2

To access all the latest features and upcoming developments, please see our v3 API.

Rate this page:

Blocks

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

Get

Retrieve a list of Blocks with addresses and response codes. You may optionally specify a date range to constrain the results.

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.

Call

GET https://api.sendgrid.com/api/blocks.get.json
GET Data api_user=apikey&api_key=your_sendgrid_api_key&date=1

Response

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

Call

GET https://api.sendgrid.com/api/blocks.get.xml
GET Data api_user=apikey&api_key=your_sendgrid_api_key&date=1

Response

<blocks>
   <block>
      <email>emaieexampexample@example.com</email>
      <status>5.1.1</status>
      <reason>host [127.0.0.1] said: 550 5.1.1 unknown or illegal user: emaieexampexample@example.com</reason>
      <created>2009-06-10 12:40:30</created>
   </block>
   <block>
      <email>emaileexampexample@example.com</email>
      <status>5.1.1</status>
      <reason>host [127.0.0.1] said: 550 5.1.1 unknown or illegal user: emaileexampexample@example.com</reason>
      <email>example@example.com</email>
      <status>5.1.1</status>
      <reason>host [127.0.0.1] said: 550 5.1.1 unknown or illegal user: example@example.com</reason>
      <created>2009-06-10 12:40:30</created>
   </block>
   <block>
      <email>example@example.com</email>
      <status>5.1.1</status>
      <reason>host [127.0.0.1] said: 550 5.1.1 unknown or illegal user: example@example.com</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.

Call

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

Response

{
  "message": "success"
}

Call

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

Response

<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.

Call

GET https://api.sendgrid.com/api/blocks.count.json
GET Data api_user=apikey&api_key=your_sendgrid_api_key

Response

{
  "count": "4"
}

Call

GET https://api.sendgrid.com/api/blocks.count.xml
GET Data api_user=apikey&api_key=your_sendgrid_api_key

Response

<result>
   <count>4</count>
</result>
Rate this page:

Need some help?

We all do sometimes; code is hard. Get help now from our support team, or lean on the wisdom of the crowd browsing the SendGrid tag on Stack Overflow.

        
        
        

        Thank you for your feedback!

        We are always striving to improve our documentation quality, and your feedback is valuable to us. How could this documentation serve you better?

        Sending your feedback...
        🎉 Thank you for your feedback!
        Something went wrong. Please try again.

        Thanks for your feedback!

        Refer us and get $10 in 3 simple steps!

        Step 1

        Get link

        Get a free personal referral link here

        Step 2

        Give $10

        Your user signs up and upgrade using link

        Step 3

        Get $10

        1,250 free SMSes
        OR 1,000 free voice mins
        OR 12,000 chats
        OR more