Rate this page:

Unique Arguments

This information will be stored as a “Not PII” field and may be used for counting or other operations as SendGrid runs its systems. These fields generally cannot be redacted or removed. You should take care not to place PII in this field. SendGrid does not treat this data as PII, and its value may be visible to SendGrid employees, stored long-term, and may continue to be stored after you’ve left SendGrid’s platform.

The SMTP API JSON string allows you to attach an unlimited number of unique arguments to your email up to 10,000 bytes. The arguments are used only for tracking. They can be retrieved through the Event API or the Email Activity page.

When passing unique_args please make sure to only use strings as shown in our examples. Any other type could result in unintended behavior.

These arguments can be added using a JSON string like this:

{
  "unique_args": {
    "customerAccountNumber": "55555",
    "activationAttempt": "1",
    "New Argument 1": "New Value 1",
    "New Argument 2": "New Value 2",
    "New Argument 3": "New Value 3",
    "New Argument 4": "New Value 4"
  }
}

These arguments can then be seen in posts from the SendGrid Event Webhook. The contents of one of these POST requests would look something like this:

Example Webhook Post Data

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

Bounces returned with the Return-Path cause `unique_rgs not to be attached to an event. This can cause issues when developing unique_args POST handling.

To apply different unique arguments to individual emails, you may use substitution tags. An example of this would look like:

{
  "sub": {
    "-account_number-": ["314159", "271828"]
  },
  "unique_args": {
    "customerAccountNumber": "-account_number-"
  }
}

Additional Resources

Rate this page:

Need some help?

We all do sometimes; code is hard. Get help now from our support team, or lean on the wisdom of the crowd browsing the SendGrid tag on Stack Overflow.

      
      
      

      Thank you for your feedback!

      We are always striving to improve our documentation quality, and your feedback is valuable to us. How could this documentation serve you better?

      Sending your feedback...
      🎉 Thank you for your feedback!
      Something went wrong. Please try again.

      Thanks for your feedback!

      Refer us and get $10 in 3 simple steps!

      Step 1

      Get link

      Get a free personal referral link here

      Step 2

      Give $10

      Your user signs up and upgrade using link

      Step 3

      Get $10

      1,250 free SMSes
      OR 1,000 free voice mins
      OR 12,000 chats
      OR more