Skip to content
Docs

Client Tagging

Client Tagging lets you attach a free-form tag to the messages you send, then report on usage and cost grouped by that tag. It’s designed for resellers and multi-tenant applications who send on behalf of their own end clients and need to attribute spend back to each one.

There’s nothing to set up. Tags are created automatically the first time you use them. Just include a clientTag when you send, and the usage rolls up under that tag in the reporting endpoint.

Tagging your sends

Section titled “Tagging your sends”

Pass clientTag when sending a single SMS or an SMS batch. On a batch, the tag is applied to every message in the request.

await smsClient.SendSmsAsync(new ConnectSmsMessage
{
    To = "+447700900123",
    Content = "Your order has shipped!",
    ClientTag = "acme-corp"   // attribute this send to your client "Acme Corp"
});

How tags are normalized

Section titled “How tags are normalized”

To keep tags consistent and reportable, every tag you send is normalized before it’s stored:

  • Converted to lowercase
  • Only a–z, 0–9 and hyphens are kept
  • Any run of other characters (spaces, punctuation, accents) becomes a single hyphen
  • Leading and trailing hyphens are trimmed
  • Truncated to a maximum of 64 characters

This means "Acme Corp", "acme corp" and "ACME, Corp!" all normalize to the same tag, acme-corp, and report together. If a tag normalizes to an empty string, it’s treated as no tag at all.

You sendStored as
Acme Corpacme-corp
ACME, Corp!acme-corp
client_42client-42
(no tag)

Usage Reporting

Section titled “Usage Reporting”

Retrieve aggregated usage and cost grouped by tag over a date range.

GET
/reporting/client-tag-report

Request Data

Section titled “Request Data”

Headers

X-Api-Key
required
string
The API Key for your Workspace.

Query Parameters

dateStart
string
format: date (YYYY-MM-DD)
Start of the reporting range (inclusive). Defaults to one month ago. Must not be after today.
dateEnd
string
format: date (YYYY-MM-DD)
End of the reporting range (inclusive). Defaults to today. Must not be after today.
clientTag
string
Filter to a single tag. Normalized the same way as when sending. If omitted, every tag is returned.

Response Data

Section titled “Response Data”

JSON Data

dateStart
string
format: date (YYYY-MM-DD)
The start date the report covers.
dateEnd
string
format: date (YYYY-MM-DD)
The end date the report covers.
summaries
array
One entry per tag, ordered alphabetically by tag.
tag
string
The normalized tag.
sentCount
integer
Total number of messages sent under this tag in the range.
sentPartsCount
integer
Total number of SMS parts sent under this tag.
totalCostEur
number
Total cost in EUR for this tag across the range.
totalCostGbp
number
Total cost in GBP for this tag across the range.
daily
array
Per-day breakdown for this tag.
date
string
format: date (YYYY-MM-DD)
The day this breakdown covers.
sentCount
integer
Messages sent on this day.
sentPartsCount
integer
SMS parts sent on this day.
totalCostEur
number
Cost in EUR on this day.
totalCostGbp
number
Cost in GBP on this day.

Example Response

Section titled “Example Response”
{
  "dateStart": "2026-05-19",
  "dateEnd": "2026-06-19",
  "summaries": [
    {
      "tag": "acme-corp",
      "sentCount": 1240,
      "sentPartsCount": 1310,
      "totalCostEur": 45.85,
      "totalCostGbp": 39.30,
      "daily": [
        {
          "date": "2026-06-18",
          "sentCount": 80,
          "sentPartsCount": 84,
          "totalCostEur": 2.94,
          "totalCostGbp": 2.52
        }
      ]
    }
  ]
}