No results from SendGrid email activity API

Question

I'm using this documentation to try and receive bounce information from the SendGrid email activity API:

https://sendgrid.com/docs/for-developers/sending-email/getting-started-email-activity-api/#filter-by-bounced-emails

But it returns no results, despite having ~50 bounces showing on our dashboard (which are viewable from the "activity" section on the SendGrid web interface).

Request:

curl --request GET \
 --url 'https://api.sendgrid.com/v3/messages?limit=100&query=status%3D%22bounced%22' \
 --header 'authorization: Bearer <<TOKEN_REMOVED>>'

Response:

{"messages":[]}

Obviously <<TOKEN_REMOVED>> is our actual token when I'm running it :)

Note - when I use the v3/suppression/bounces endpoint to return everything it works fine (responds with a huge JSON of bounces), however I'd like to be able to use the more flexible messages endpoint for querying a specific email etc.

curl --request GET \
--url https://api.sendgrid.com/v3/suppression/bounces \
--header 'accept: application/json' \
--header 'authorization: Bearer <<TOKEN_REMOVED>>' \ 
--header 'content-type: application/json' \
--data '{}' \

Answer 1

There are two places that document the messages API usage:

• The "getting started" docs
• The API docs

However with regards to status query parameter, the "getting started" guide has outdated examples, which wrongly include &query=status%3D%22bounced%22'.

In the query reference it is explicitly mentioned that status can only be one of the following:

Valid values include "delivered","not_delivered", and "processing"

However, since sendgrid also relies on its own /messages API to retrieve values in the GUI, inspecting the traffic revealed it uses the type query param to identify bounces (see image below).

Disclaimer: This type parameter does not seem to be documented so use it at your own risk.

Further reading: If you want to be informed about failed email-events in a reactive way without periodically polling the /messages endpoint, you should checkout sendgrid's webhooks mechanism, which will call an endpoint of your choice in order to deliver information about the email status to you, including whether it bounced or not.