Subscriber data model

When talking about the Data Structure of AbuseHQ, we think of the data that can be influenced by you and will influence your setup and your capabilities down the line. Don't worry; most things can be adjusted and changed afterward, nevertheless it's never wrong taking a minute upfront and make a plan.

AbuseHQ knows four hierarchy layers consisting of Subscriber, Contract, Case, and Event which stand in a relationship as seen in the graphic.

Let's look at each of them from the bottom up:

If you think of incoming Abuse Reports, like an ARF Feedbackloop or a Bulk Report by Shadowserver, an incoming Abuse Report will lead to at least one but can also result in some individual cases to hundreds or thousands of Events. AbuseHQ takes care of splitting them up correctly, so you always have a similar perception of what is happening.

A Case is the next higher layer, which will function as a container for Events. Case Creation Rules, including Case Groups and specific Subscriber Resolving, will determine if an Event will be responsible for creating a new Case or will be attached to Cases. Agents and AbuseHQ Automation will mainly work on cases in the daily work.

A Contract is an optional layer you can decide whether to use. It is even possible to use it in a few and not to use it in a few other cases. We used the word Contract since it makes the most syntactical sense. Still, it is just another layer that does not have to reflect a contract but can also reflect, for example, a Campaign in the case of an E-Mail Service Provider or also a Sub-Feature within a contract. This depends entirely on you and your use case. If you need clarification, drop us a note in chat or at support@abusix.com, and we will be happy to help you with examples from other customers.

Finally, and therefore the highest layer is the Subscriber itself. We call them Subscribers; you may also call them customers or clients. The Subscriber is mandatory information. Without Subscriber information, there will be no Case created, and incoming emails will end up in the mailbox.

One of the essential things in AbuseHQ is the Subscriber Resolver. The Subscriber Resolver will ensure that all events will end up in the right Cases associated with (the correct Contract and) the correct Subscriber. If an Event can't be resolved, it will not create a Case or be attached to it.

This is important because we are trying to solve our issues by solving a customer's issues, and not knowing who the Subscriber is, makes it impossible. Think about it from a Cable Provider point of view, where we only know which IP address was sending the Spam Message at what time. Subscriber Resolving will ensure we can resolve the IP and Date to a Subscriber ID.

Now, aggregating incoming events already in Cases and correctly allocating those Cases to the correct Contracts and Subscribers are helpful. In some cases, you want to add more detail about a Contract or a Subscriber to AbuseHQ to alter your decision based on additional information.

Such information can, for example, be as simple as if the Subscriber has VIP status. Because if he is a VIP, you'll handle his Cases differently. It could also be the creation date of the Contract/Subscriber or his email address to send messages directly from AbuseHQ Bulk Mailer.

An example JSON looks like this:

{
    "subscriber": {
        "id": "<subscriber_id>",
        "resolver_data": {
            "<subscriber_key1>": "<subscriber_value1>",
            "<subscriber_key2>": "<subscriber_value2>"
        }
    },
    "contract": {
        "id": "<contractid>",
        "resolver_data": {
            "<contract_key1>": "<contract_value1>",
            "<contract_key2>": "<contract_value2>"
        }
    } 
}

This information can be available via API Subscriber Resolver and the X-Header Resolver.