The API is documented as accepting a string for custom_args, but when provided with a string, it responds with an error suggesting it expects an object.
For example:
curl https://api.sendgrid.com/v3/mail/send -X POST -H 'Authorization: Bearer [redacted]' \
-H 'content-type: application/json' \
-d '{
"personalizations": [ { "to": [ { "email": "you@you.you" } ] } ],
"from": { "email": "me@me.me" },
"content": [{ "type": "text/plain", "value": "sample payload" }],
"subject": "test subj",
"custom_args": "this is a string"
}'
Returns:
{"errors":[{"message":"Invalid type. Expected: object, given: string.","field":"custom_args","help":"http://sendgrid.com/docs/API_Reference/Web_API_v3/Mail/errors.html#message.custom_args"}]}%
Obviously it seems the documentation is broken. My question is: are there any constraints on the object that can be passed for this field?
I think you're right, the documentation is faulty. The custom_args field only accepts an object.
As for constraints, they don't have that well-documented either, but I did find https://www.twilio.com/docs/sendgrid/for-developers/sending-email/personalizations which included the following statement;
Keys within objects such as
custom_argswill be merged. If any of the keys conflict, the keys in thepersonalizationsobject will replace the message level object's keys.
I concluded when I did my implementation that all the keys in my custom_args should not be a key already used by SendGrid, so using a email as a key for one of my custom_args would be inadvisable. I recommend creating a prefix of some sort for your keys that is unique to your implementation, such as higgmp_email to ensure there is no conflict.