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.

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": "<body><p><strong>Lorem Ipsum</strong></p><br /></body>",
      "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.