SendGrid unique arguments with individual emails

Question

I trying to set up a list of unique arguments per each email, the official reference of the SMTP api describes this feature quite briefly, here.

And the API docs of the SendGrid PHP library the I am using, also didn't help much:

 /** 
   * setUniqueArguments
   * Set a list of unique arguments, to be used for tracking purposes
   * @param array $key_value_pairs - list of unique arguments
   */
  public function setUniqueArguments(array $key_value_pairs)
  {
    $this->header_list['unique_args'] = $key_value_pairs;
    return $this;
  }

  /**
   * addUniqueArgument
   * Set a key/value pair of unique arguments, to be used for tracking purposes
   * @param string $key   - key
   * @param string $value - value
   */
  public function addUniqueArgument($key, $value)
  {
    $this->header_list['unique_args'][$key] = $value;
    return $this;
  }

So in fact, I based my implementation on the obvious logical conclusion, and decided to create multi-dimensional json for the unique-arguments part of the header, with one to one correspondence to the substitution values array, and to the recipients array, but unfortunately, that didn't work, and resulted in an invalid XSMTP API header error being bounced back to my email.

If anyone have used this feature before, and can instruct me briefly on how to use it correctly (perhaps calling addUniqueArgument after each addTo?), it can be a great help for me.

Answer 1

I see that you're mentioning unique arguments first but then you're mentioning substitutions that are a completely unrelated matter. Unique arguments apply to the API call as a whole, for example those may contain a batch ID in your system so that you can more easily match the email events to your data. Substitutions, however, is basically string replacement in emails to personalize each email for its recipient and those apply to each recipient of the email instead of the API call.

Sendgrid unique arguments

You don't have to mess with the JSON request headers if you're using their API library, simply use the library as any other PHP object. For example, if you have to set three variables, var1, var2, var3 it's either this:

$Sendgrid -> setUniqueArguments(array(
    'var1' => 'value1',
    'var2' => 'value2',
    'var3' => 'value3'
));

or this:

$Sendgrid -> addUniqueArgument('var1', 'value1');
$Sendgrid -> addUniqueArgument('var2', 'value2');
$Sendgrid -> addUniqueArgument('var3', 'value3');

The difference being that the first option setUniqueArguments completely replaces any other variables you've added before but the second one, addUniqueArgument, adds a variable to the existing ones.

Sendgrid substitutions

Let's say you're using their API library and you have 2 recipients, bob@example.com and alice@example com, and you need to mention their name in the email. In this case you use a placeholder string in the body of the email, basically anything that wouldn't occur normally. In our case, let's assume it could be:

Hello <<Name>>

where <<Name>> is the placeholder for the recipients name. In this case you can construct the API call as such (I'm leaving out the parts related to email content, etc.):

$Sendgrid -> addTo('bob@example.com');
$Sendgrid -> addTo('alice@example.com');
$Sendgrid -> addSubstitution('<<Name>>', array('Bob', 'Alice'));

The values in the addSubstituion call must be in the same order as the recipient list.