SendGrid: "batch id not found" - sendgrid

Question

I'm playing around with the v3 API and trying to demo the concept of scheduling emails and then cancelling them. Here is what I did:
Created a batch with POST https://api.sendgrid.com/v3/mail/batch and got batch a batch ID
Did a mail send with POST https://api.sendgrid.com/v3/mail/send and included that batch ID as the batch_id parameter and put in a future send_at time
Attempted to pass that batch ID into POST https://api.sendgrid.com/v3/user/scheduled_sends/:batch_id
However the latter call fails as 404 Not Found with "message": "batch id not found". In fact it would seem that however many batch IDs I create, attempting to update them always yields this not-found message. The result is, the scheduled send cannot be cancelled, and the email sends at the appointed time. I should add that attempting to GET /v3/mail/batch/{batch_id} returns an empty array [].
Am I doing something wrong here?? Is this a limitation of the free account perhaps?
EDIT: I'm going to add some raw details to show what I am doing. I am doing these in Postman but I will export in cURL syntax to demonstrate.
First I create a batch:
curl --location --request POST 'https://api.sendgrid.com/v3/mail/batch' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <token redacted>' \
--data-raw ''
Response: {"batch_id":"OWU0NzgxYzUtMjkzZS0xMWVkLTg5NDAtYWUyMDAwNjVjZGU0LTZiODk2MDliZA"}
So now the next thing I want to try is to verify that batch ID:
curl --location --request GET 'https://api.sendgrid.com/v3/user/scheduled_sends/OWU0NzgxYzUtMjkzZS0xMWVkLTg5NDAtYWUyMDAwNjVjZGU0LTZiODk2MDliZA' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <token redacted>'
The response is, oddly, a 200 OK with just [] which doesn't seem right does it? I created a batch and it has an ID, so why can't I verify its existence?
Documentation here states: https://docs.sendgrid.com/api-reference/cancel-scheduled-sends/validate-batch-id
When you pass a valid batch_id to this endpoint, it will return a 200
status code and the batch ID itself.
If you pass an invalid batch_id to the endpoint, you will receive a
400 level status code and an error message.
A batch_id does not need to be assigned to a scheduled send to be
considered valid. A successful response means only that the batch_id
has been created, but it does not indicate that it has been associated
with a send.
Interestingly if I put any arbitrary string in that URL instead of a batch ID, I also get a 200 OK with empty array. I cannot even reproduce what the document is saying about receiving a 400 error for an invalid ID.
However if I take it on faith that the batch WAS created, I would go ahead and try to send an email with it:
curl --location --request POST 'https://api.sendgrid.com/v3/mail/send' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <token redacted>' \
--data-raw '{
"batch_id": "OWU0NzgxYzUtMjkzZS0xMWVkLTg5NDAtYWUyMDAwNjVjZGU0LTZiODk2MDliZA",
"send_at": 1661969713,
"personalizations": [{
"to": [{
"email": "thatemail#mycompany.com",
"name": "John Doe"
}
]
}],
"from": {
"email": "myemail#mycompany.com",
"name": "Jane Doe"
},
"reply_to": {
"email": "customer_service#example.com",
"name": "Example Customer Service Team"
},
"subject": "Example Email 6",
"content": [{
"type": "text/html",
"value": "<p>Test email!</p><p>%open-track%</p>"
}
],
"custom_args":{
"sf-id": "some-arbitrary-id6",
"sf-org-id": "some-arbitrary-org-id"
},
"mail_settings": {
"sandbox_mode": {
"enable": false
}
},
"tracking_settings": {
"click_tracking": {
"enable": true,
"enable_text": false
},
"open_tracking": {
"enable": true,
"substitution_tag": "%open-track%"
},
"subscription_tracking": {
"enable": false
}
}
}
'
At the time of writing that timestamp is for 3h from now, resolving at 2:15PM August 31st Eastern Time. I send that call and get 202 Accepted.
Then, finally, I attempt to pause the batch.
curl --location --request PATCH 'https://api.sendgrid.com/v3/user/scheduled_sends/OWU0NzgxYzUtMjkzZS0xMWVkLTg5NDAtYWUyMDAwNjVjZGU0LTZiODk2MDliZA' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <token redacted>' \
--data-raw '{"status": "pause"}'
My response is a 404 NOT FOUND with:
{
"errors": [
{
"field": null,
"message": "batch id not found"
}
]
}
So... what is going on here???

Answer 1

So a few things:
It turns out I was missing a step here. The first time I want to put in a pause or cancel on a batch, I actually need to POST /v3/user/scheduled_sends/ with batch_id in the request body. I was trying PATCH. Strange behaviour here as the batch ID already exists, but OK.
After my first successful test of this, the entire behaviour of the GET /v3/mail/batch/{batch_id} API changed for me. I am no longer able to reproduce getting back an empty array. Every response is either a success with the batch ID or a fail.
I don't know why these behaviours changed, but they did. There may be some quirk in which fresh accounts that have never paused/cancelled a batch simply do not have a functional "validate batch" call. Now that I have done a successful pause for the first time, the behaviour of GET /v3/mail/batch/{batch_id} finally matches the documentation.