Working with Categories
Warning
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 have left SendGrid's platform.
Categories can help organize your email analytics by enabling you to group emails by type. Just as you can view the statistics on all your email activity, you can go a step further and view the statistics by a particular category.
Categories can be added using either the X-SMTPAPI header or the Twilio SendGrid Web API.
You can use the X-SMTPAPI header to add categories to your email. This will allow you to track emails based on your own categorization system.
Categories must be in 7-bit encoding using the US-ASCII character set.
In the following example, SendGrid would associate statistics for the email containing that header with the category Example Category.
1{2"category": "Example Category"3}
You can also work with categories using the Twilio SendGrid Categories REST API. See our API reference for more information and examples.
Warning
When passing category please make sure to only use strings as shown in our examples. Any other type could result in unintended behavior.
Info
Categories should be used to group messages together by broad topic. If you need to attach unique data or identifiers to a message, use Unique Arguments instead.
You can assign up to 10 categories per message. We recommend sending no more than ~100 total unique categories, as this increases your ease of use in the Statistics area. A high rate of unique categories on your account can negatively impact the rate at which Twilio SendGrid processes the messages you send.
Twilio SendGrid limits the number of stored category statistics available per user. Accounts on a paid plan are allowed 1,000 categories daily. Accounts on a free plan are allowed 100 categories daily. The limit of 10 categories per email message remains in place.
If you exceed the maximum number of categories sent, the top-used categories — 100 for free plans or 1,000 for paid plans — are retained, and all remaining categories are permanently deleted. Twilio SendGrid determines a user's top categories by querying and ranking categories by the total number of statistics for each category. If multiple categories have the same statistics count, Twilio SendGrid sorts the categories alphabetically by name.
Categories are deleted on a 7-day rolling basis. All of your categories are available, without limitation, for the first 7 days after they are initially sent. Category stats are then trimmed on a rolling basis from the eighth day prior to the current day.
For example, if you send a total of 2,000 unique categories on the first day of a month, you can access the stats for all 2,000 categories for the following 7 days. On the eighth day, only the top 100 (free plans) or top 1,000 (paid plans) categories from the first day remain available. On the ninth day, categories in excess of the limit are trimmed from the second day, and so on.
Because Twilio SendGrid uses this rolling mechanism to delete category statistics, you can retrieve and store the statistics on your own systems before they are deleted. You can configure the Twilio SendGrid Event Webhook or use the Categories API to retrieve all the statistics that you wish to retain before they are deleted from Twilio SendGrid's systems.
If this limit change applies to you, it may be a good opportunity to evaluate how you use category statistics. Categories are meant to group messages by broad topics. However, they are not intended as tags you can use to attach unique data to an email. Twilio SendGrid provides unique arguments specifically for this purpose, and they may be more appropriate for customers running into category statistic limits.