Unique Arguments

(error)

Data stored as non-personally identifiable information

Twilio SendGrid stores this data in a JSON object as non-personally identifiable information (PII). You can't redact or remove these fields. Don't place PII in this field. Twilio SendGrid doesn't treat this data as PII. These values might be visible to Twilio employees, stored long-term, and may continue to be stored after you've left the Twilio SendGrid platform.

To attach arguments to your SMTP email, add the unique_args JSON object to your SMTP API POST request. For tracking purposes, you can attach an unlimited number of unique arguments to your email up to 10,000 bytes in length. To retrieve their values, use the Event API or the Email Activity.

Only the Twilio SendGrid SMTP API and V2 Mail Send API use unique arguments. The V3 Mail Send API uses custom arguments.

The unique_args object only accepts string values. Using any other data type could result in unintended behavior.

Example of adding an argument with a JSON string

1{
2  "unique_args": {
3    "customerAccountNumber": "55555",
4    "activationAttempt": "1",
5    "New Argument 1": "New Value 1",
6    "New Argument 2": "New Value 2",
7    "New Argument 3": "New Value 3",
8    "New Argument 4": "New Value 4"
9  }
10}

The SendGrid Event Webhook displays these arguments. The contents of one of these POST requests resembles the following example:

Example webhook post data

1{
2  "sg_message_id": "145cea24eb8.1c420.57425.filter-132.3382.5368192A3.0",
3  "New Argument 1": "New Value 1",
4  "event": "processed",
5  "New Argument 4": "New Value 4",
6  "email": "example@example.com",
7  "smtp-id": "<145cea24eb8.1c420.57425@localhost.localdomain>",
8  "timestamp": 1399331116,
9  "New Argument 2": "New Value 2",
10  "New Argument 3": "New Value 3",
11  "customerAccountNumber": "55555",
12  "activationAttempt": "1"
13}

(error)

Return-Path interferes with unique_args object

If your email has bounces with the Return-Path, the unique_args don't attach to the event. When developing unique_args POST handling, account for this issue with Return-Path.

To apply different unique arguments to individual emails, you might use substitution tags. An following example shows how substitution tags would be used:

Example of using substitution tags

1{
2  "sub": {
3    "-account_number-": ["314159", "271828"]
4  },
5  "unique_args": {
6    "customerAccountNumber": "-account_number-"
7  }
8}