---
title: Metadata and Tags
description: In addition to MailingID and MessageID, Metadata and Tags allow you to include additional data that persists through the message lifecycle.
---
[Skip to content](https://help.socketlabs.com/docs/metadata-and-tags#main-content)
English
Show submenu for translations
[Contact us](https://help.socketlabs.com/docs/kb-tickets/new?hsLang=en)
[](https://www.socketlabs.com/)
Open main navigation
Close main navigation
- English
Show submenu for translations
- [Contact us](https://help.socketlabs.com/docs/kb-tickets/new)
SocketLabs is here to help!
- There are no suggestions because the search field is empty.
1. [Help Center](https://help.socketlabs.com/docs?hsLang=en)
2. [Advanced](https://help.socketlabs.com/docs/advanced?hsLang=en)
# Metadata and Tags
## In addition to MailingID and MessageID, Metadata and Tags allow you to include additional data that persists through the message lifecycle.
Just like [MailingID and Message ID](https://help.socketlabs.com/docs/message-mailing-ids?hsLang=en), Metadata and Tags are set in the API call or inserted as a message header for SMTP.
Metadata and Tags combined are limited to a 12.5KB total payload limit.
### Tags
Tags allow you to add descriptors to segment your mail into general categories.
Limits:
- 25 tags per message
- Must remain below a 12.5KB total payload limit (including metadata)
When retrieving aggregated data and reports from the SocketLabs API or SocketLabs Spotlight reporting tools, prebuilt aggregate data is only available for the 100 most frequently used tag values for the past 16 days.
### Metadata
Metadata is a collection of key and value pairs to help you understand more specific details about the message performance.
Limits:
- Create using a Key-Value pair
- Up to 10 Key-Value pairs per message
- Key-Value pairs combined should be less than 100 characters
- Must remain below 12.5KB total payload limit (including tags)
### SMTP Insertion
Adding Tags and Metadata to when using the SocketLabs SMTP relay mechanism to transmit messages is achieved by adding the x-xsData header. For example:
```
x-xsData: {"Tags":["Transactional","OrderConfirmation","WebsiteOrder"],"Meta":[{"Key":"CustomerID","Value":"5227581"},{"Key":"DynamicImagesUsed","Value":"Hero-BL741"}]}
```
### HTTP Injection API Insertion
Adding Tags and Metadata when using the SocketLabs Injection API is as simple as specifying them as message properties.
```
{ "serverid": 12345, "apikey": "123456abc123456", "messages": [ { "to": [ { "emailaddress": "test@example.com" } ], "from": { "emailaddress": "support@socketlabs.com" }, "subject": "Sending Basic Complex Example", "textbody": "Lorem Ipsum", "htmlbody": "Lorem Ipsum
", "mailingid": "MyMailingId", "messageid": "MyMsgId", "metadata": [ { "key": "x-mycustommetadata", "value": "I am custom metadata" } ], "tags": [ "Basic-Complex-Example", "postman-Example", "charset": "utf-8", "replyto": { "emailaddress": "developers@wesend.email" } ] } ]}
```
SocketLabs client libraries all include full support for Tags and Metadata: https://help.socketlabs.com/docs/api-libraries
Please see the full HTTP Injection API documentation for more information:
Injection API (Simple): https://docs.socketlabs.com/#b11506e2-a47c-484f-a0ee-5b4471905196
Injection API (Complex): https://docs.socketlabs.com/#c312e4a0-a485-429b-a611-3a31cfc2d64a
### Reporting
Tags and metadata will be included in webhook events, SocketLabs API responses and visible in the Message Event Timeline on the Message Detail Reports within your account.
Tags are also available for filtering on aggregate reports within the portal.
- [Fundamentals](https://help.socketlabs.com/docs/fundamentals?hsLang=en#main-content)
- [StreamScore](https://help.socketlabs.com/docs/fundamentals?hsLang=en#streamscore)
- [Reports](https://help.socketlabs.com/docs/fundamentals?hsLang=en#reports)
- [Frequently Asked Questions](https://help.socketlabs.com/docs/fundamentals?hsLang=en#frequently-asked-questions)
- [Advanced](https://help.socketlabs.com/docs/advanced?hsLang=en#main-content)
- [Security](https://help.socketlabs.com/docs/advanced?hsLang=en#security)
- [DNS Authentication](https://help.socketlabs.com/docs/dns-authentication?hsLang=en#main-content)
- [DKIM](https://help.socketlabs.com/docs/dns-authentication?hsLang=en#dkim)
- [SPF and Custom Bounce Domain](https://help.socketlabs.com/docs/dns-authentication?hsLang=en#spf-and-custom-bounce-domain)
- [Deliverability](https://help.socketlabs.com/docs/deliverability?hsLang=en)
- [For Developers](https://help.socketlabs.com/docs/for-developers?hsLang=en#main-content)
- [Event Webhooks](https://help.socketlabs.com/docs/for-developers?hsLang=en#event-webhooks)
- [Integrations](https://help.socketlabs.com/docs/integrations?hsLang=en#main-content)
- [Languages and Frameworks](https://help.socketlabs.com/docs/integrations?hsLang=en#languages-and-frameworks)
- [Mail Servers](https://help.socketlabs.com/docs/integrations?hsLang=en#mail-servers)
- [Web Clients and Plug-ins](https://help.socketlabs.com/docs/integrations?hsLang=en#web-clients-and-plug-ins)
- [Mail Clients](https://help.socketlabs.com/docs/integrations?hsLang=en#mail-clients)
- [Marketing Tools](https://help.socketlabs.com/docs/marketing-tools?hsLang=en#main-content)
- [Tips and Tricks](https://help.socketlabs.com/docs/marketing-tools?hsLang=en#tips-and-tricks)
- [Troubleshooting](https://help.socketlabs.com/docs/troubleshooting?hsLang=en#main-content)
- [SocketLabs Inbound SMTP Gateway Errors](https://help.socketlabs.com/docs/troubleshooting?hsLang=en#socketlabs-inbound-smtp-gateway-errors)
- [SocketLabs Outbound SMTP Errors](https://help.socketlabs.com/docs/troubleshooting?hsLang=en#socketlabs-outbound-smtp-errors)
- [Spotlight Email Analytics](https://help.socketlabs.com/docs/spotlight-email-analytics?hsLang=en)
- [Hurricane MTA](https://help.socketlabs.com/docs/hurricane-mta?hsLang=en#main-content)
- [Advanced Hurricane Usage](https://help.socketlabs.com/docs/hurricane-mta?hsLang=en#advanced-hurricane-usage)
- [Upgrading Hurricane](https://help.socketlabs.com/docs/hurricane-mta?hsLang=en#upgrading-hurricane)
- [Troubleshooting](https://help.socketlabs.com/docs/hurricane-mta?hsLang=en#troubleshooting)
- [Hurricane Maintenance](https://help.socketlabs.com/docs/hurricane-mta?hsLang=en#hurricane-maintenance)
- [Getting Started with Hurricane](https://help.socketlabs.com/docs/hurricane-mta?hsLang=en#getting-started-with-hurricane)
- [Basic Hurricane Usage](https://help.socketlabs.com/docs/hurricane-mta?hsLang=en#basic-hurricane-usage)
- [Complex Sender](https://help.socketlabs.com/docs/complex-sender?hsLang=en)
[](https://www.socketlabs.com)
Copyright © 2026, SocketLabs LLC