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, 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 allow you to add descriptors to segment your mail into general categories.


  • 25 tags per message
  • Must remain below a 12.5KB total payload limit (including metadata)


Metadata is a collection of key and value pairs to help you understand more specific details about the message performance.


  • 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": ""
      "from": {
        "emailaddress": ""
      "subject": "Sending Basic Complex Example",
      "textbody": "Lorem Ipsum",
      "htmlbody": "<body><p><strong>Lorem Ipsum</strong></p><br /></body>",
      "mailingid": "MyMailingId",
      "messageid": "MyMsgId",
      "metadata": [
          "key": "x-mycustommetadata",
          "value": "I am custom metadata"
      "tags": [
      "charset": "utf-8",
      "replyto": {
    "emailaddress": ""

SocketLabs client libraries all include full support for Tags and Metadata: 

Please see the full HTTP Injection API documentation for more information: 

Injection API (Simple): 

Injection API (Complex):


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.

A future update to the SocketLabs Portal will include using Tags for report filtering.