Message Intelligence API Operations


This is the detailed definition of the message intelligence module operations.

These operations provide the ability to request specific relationship or message data information from the LogiQ instance. The requested data can be returned in different formats to suit the external system.

get_relationships operation


This operation returns the known relationship information between local and remote communicators.
These communicators can be defined using unique email addresses, or partial addresses such as domains or wildcards.

The operation searches for relationships with local communicators defined in the parameter.

Relationships with remote communicators are returned if matching the parameter.
Relationships with remote communicators are not returned if matching the parameter.
Mixed case email addresses will be converted to lower case e.g. JO@acme.com will be converted to jo@acme.com.

download
Note: The parameter takes precedence over the parameter

The relationships are returned as a list of email addresses or domains according to the attribute in the request.

  • <output> = address will return email addresses.

<search> = “*@acme.com” will search all the local email addresses at acme.com and return a list of associated remote email addresses that have relationships.

<search> = “me@acme.com” will return only external email addresses that me@acme.com has a relationship with.

  • <output> = domain will return email domains.

<search> = ”*@acme.com” will search all the local email addresses with a domain of acme.com and return the domains that have relationships.

<search> = me@acme.com will return domains that me@acme.com has a relationship with.

download

Note: <Search> can only be a local communicator.
Specific remote communicators or domains can be identified in the <include> parameter, in this case search all local communicators using a wildcard <search> such as *@local.com

Note: <output> = domain returns aggregated information of all relationships within the domain.
The returned <created> date is the earliest one found, and the <lastout> and <lastin> are the latest found.

The execution time is dependent on the requested search. A search for a local email address or local domain is quicker than a remote subscriber or domain. This is due to the indexing of the information within LogiQ.
Information is available from the date of the LogiQ installation until the current time. The time latency is dependent on the LogiQ deployment.
The information returned can be filtered by the parameters output, start and end.

get_relationships request


Operation
request
Elements and attributes
<module> request | name | context | format | output | start | end
<search> search expression
<include>
<exclude>
<aliases>
<alias> name Alias

Get_relationships module element format

<module> Value Description
request “get_relationships” Requested operation
name “intel” Relationship Analytics module
context “*”
group
domain
Full context
domain group context
domain context
format “tsv”
“gml”
“xml”
Output data in TSV format (e.g.  MS Excel)
Output data in GML format (e.g. Gephi etc.)
Output data in XML format (default)
output “address”
“domain”
Requests only email addresses (default)
Requests only domains
start yy-mm-dd hh:mm:ss Filter for dates after start (not inclusive)
If not defined defaults to 1970-01-01
end yy-mm-dd hh:mm:ss Filter for dates before end (not inclusive)If not defined defaults to the time request was received by LogiQ

Get_relationships module element attributes

The context attribute defines the access level at which the request is operated, given the correct login credentials.

  • Administrators have full access to the entire system.
  • Domain group administrators may only access lists, reporting and configuration relevant to their domain group and its domains.
  • Domain administrators may only access lists, reporting and configuration relevant to their domains.
<search> Value Description
search String A local address, domain, domain wildcard, domain group, domain list or address list
Multiple types cannot be mixed.

Get_relationships search element attributes

Multiple search elements may be included; however search elements must be of the same type. i.e. address, domain or domain group.)

Search data Format Description
address a@b Email address, e.g. me@acme.com
address list a@b,c@d A comma separated list of address(es)
domain a.b Domain name, e.g. acme.com
domain list a.b,c.d A comma separated list of domain(s)
domain wildcard *@a.b All email addresses related to the domain e.g. *@acme.com
domain group *@a A subset of a domain name e.g. *@acme will provide acme.net, acme.com, acme.a.b etc.

Get_relationships search attribute

<include> Value Description
include String A remote address, domain or PERL regex

Get_relationships include element attributes

<exclude> Value Description
exclude String A remote address, domain or PERL regex. This takes precedence over <include>

Get_relationships exclude element attributes

Multiple include or exclude elements may be included; however elements must be of the same type. i.e. address or domain)

include and exclude data Format Description
address a@b Email address, e.g. me@remote.com
address list a@b,c@d A comma separated list of address(es)
domain a.b Domain name, e.g. remote.com
domain list a.b,c.d A comma separated list of domain(s)

The <include> and <exclude> parameters can also be defined as a PERL regex :

  • ^          start of string
  • $          end of string
  • .           single character
  • +          one or more of previous character
  • ?           zero or more of previous character

download

Note: Include and exclude filters are remote communicators.

Aliases


Aliases provide a mechanism to translate domain or email strings to friendly names. Multiple alias definitions can be defined.

<aliases>
<alias name=”Fred Smith”>fred@acme.com</alias>
<alias name=”Jo Brown”>jo@acme.com</alias>
</aliases>

Aliases do not take wildcards.

Aliases can be mixed case, but the original email address will be converted to lower case by the API. E.g. <alias name=”Jo Brown”>JO@acme.com</alias> will only match jo@acme.com.

<alias> Value Description
alias String Name to place in data as substitute
name String Name to substitute

Get_relationships alias element attributes

The alias data allows friendly names to be substituted in the returned data

<aliases>
<alias name=”alias1”>name1</alias>
<alias name=”alias2”>name2</alias>
</aliases>

Aliases definition


<request user=”username” type=”transaction” session=”session“>
<module request=”get_relationships” name=”intel” context=”context” format=”format” output=”output” start=”start” end=”end”>
<search>search</search>
<include>include</include>
<exclude>exclude</exclude>
<aliases>
<alias name=”alias”>name</alias>
<aliases>
</module>
</request>

Get_relationships request

get_relationships response


The response conforms to the standard module response.

get_relationships errors


<error> element is included if request=”ERROR”

Element Error Meaning
<error> “NO_SEARCH” search missing
  “NO_FORMAT” format missing
  “NO_OUTPUT” output missing
  “INVALID_SEARCH” Key supplied was not a valid local domain, domain group or missing an @
  “MIXED_SEARCH” Search contains a mixture of key types
  “INVALID_DATE” The start or end dates are incorrect

Get_relationships errors

get_relationships data format


download

Note: The data is not sorted; therefore keys with wildcards (*@acme.com) will not group remote users.

Note: The data provides the active relationships from the current time to the LogiQ expiry period.
This expiry period is set by the LogiQ administrator.

XML data format


Data Elements and attributes
<records>
<rec>
<local>
<remote>
<type>
<ci>
<co>
<created>
<lastin>
<lastout>

Get_relationships response format

<records> Value Description
<rec> element Details of a relationship between a local subscriber and a remote subscriber

Get_relationships response records element

<rec> Format Description
<local> Email address Local email address
<remote> Email address Remote email address
<type> wl | bl Listing type
<ci> Numeric Number of communications from remote
<co> Numeric Number of communications to remote
<created> 0 – 4294967295 Time of initial communication, seconds from EPOCH
<lastin> 0 – 4294967295 Time of last communication from remote, seconds  from EPOCH
<lastout> 0 – 4294967295 Time of last communication to remote, seconds from EPOCH

Get_relationships response rec elements

<records>
<rec>
<local>steve@remote.com</local>
<remote>fred@acme.com</remote>
<type>wl</type>
<ci>0</ci>
<co>3</co>
<created>1346866227</created>
<lastin>1346866227</lastin>
<lastout>1346866229</lastout>
</rec>
<rec>
<local>dave@support.biz </local>
<remote>joe@acme.com </remote>
<type>wl </type>
<ci>12 </ci>
<co>7 </co>
<created>1310444597 </created>
<lastin>1333501871 </lastin>
<lastout>1333502453 </lastout>
</rec>
</records>

Example – Get_relationships XML output

TSV data format


The response consists of several lines containing tab separated values.
download
Note: the time fields in TSV format are compatible with spread sheets.

Tab stop Format Description
1 Email address <local>
2 Email address <remote>
3 wl | bl <type>
4 Numeric <ci>
5 Numeric <co>
6 YYYY-MM-DD HH:MM:SS <created>
7 YYYY-MM-DD HH:MM:SS <lastin>
8 YYYY-MM-DD HH:MM:SS <lastout>

Get_relationships tsv format

steve@remote.com fred@acme.com wl 0 3 2012-09-05 17:30:27 2012-09-05 17:30:27 2012-09-05 17:30:29

Example – Get_relationships TSV output

get_messagedata operation

This operation is used to return a historical list of messages, essentially a timeline of communication for a relationship.

The execution time is dependent on the start and end of the requested data. A linear increase in time is added for each day between the start and end dates. This is due to the storage of the information within LogiQ. Information is available from the date of the LogiQ installation until the current time.

download
Note: A communication from a remote communicator it is recorded against the local communicator and the transaction is shown as inbound.

download
Note: The information is sorted such that the most current information is returned first.

get_messagedata request


Operation
request
Elements and attributes
<module> request | name | context | method | format | search | start | end
<search> search expression

Get_messagedata module element format

<module> Value Description
request “get_messagedata” Requested operation
name “intel” Relationship Analytics module
context “*”
group
domain
Full context
domain group context
domain context
method “get”
“delete”
“getdelete”
Return the data requested without deleting
Delete the previously requested data
Return and then delete the data
format “tsv”
“xml”
Output data in TSV format (e.g.  MS Excel)
Output data in XML format
search Regular expression PERL formatted regular expression for search
start yy-mm-dd hh:mm:ss Filter for dates after start (not inclusive)
end yy-mm-dd hh:mm:ss Filter for dates before end (not inclusive)

Get_messagedata module attributes

<search> Value Description
search String The information to match which can be a value of
address, domain, domain wildcard, domain group, domain list or address list
Multiple value types cannot be mixed.

Get_messagedata search element attributes

Multiple search elements may be included; however search elements must be of the same type. i.e. address, domain or domain group.)

Search data Format Description
address a@b Email address, e.g. me@acme.com
address list a@b,c@d A comma separated list of address(es)
domain a.b Domain name, e.g. acme.com
domain list a.b,c.d A comma separated list of domain(s)
domain wildcard *@a.b All email addresses related to the domain e.g. *@acme.com
domain group *@a A subset of a domain name e.g. *@acme will provide acme.net, acme.com, acme.a.b etc.

Get_messagedata search attribute

<include> Value Description
include String A remote address, domain or PERL regex

Get_messagedata include element attributes

<exclude> Value Description
exclude String A remote address, domain or PERL regex. This takes precedence over <include>

Get_messagedata exclude element attributes

Multiple include or exclude elements may be included; however elements must be of the same type. i.e. address or domain)

include and exclude data Format Description
address a@b Email address, e.g. me@remote.com
address list a@b,c@d A comma separated list of address(es)
domain a.b Domain name, e.g. remote.com
domain list a.b,c.d A comma separated list of domain(s)

Get_messagedata include and exclude element attributes

The <include> and <exclude> parameters can also be defined as a PERL regex.

  • ^          start of string
  • $          end of string
  • .           single character
  • +          one or more of previous character
  • ?           zero or more of previous character

download
Note: Include and exclude filters are remote communicators.

<request user=”user” type=”transaction” session=”session“>
<module request=”get_messagedata” name=”intel” context=”context” format=”format” method=”method” start=”start” end=”end”>
<search>search</search>
<include>include</include>
<exclude>exclude</exclude>
</module>
</request>

Example – Get_messagedata request

get_messagedata response


The response conforms to the standard module response.

get_messagedata errors


<error> element is included if request=”ERROR”

Element Error Meaning
<error> “NO_SEARCH” search missing
  “NO_OUTPUT” output missing
  “NO_DATA” Source data is not available
  “INVALID_SEARCH” Key supplied was not a valid local domain, domain group or missing an @
  “MIXED_SEARCH” Search contains a mixture of key types
  “INVALID_DATE” The start or end dates are incorrect

Get_messagedata errors

get_messagedata data format


The data can be requested in different formats according to the output parameter; if no format is specified in the request then XML format is used.

XML data format


Data Elements and attributes
<records>
<msg>
<date>
<ip>
<local>
<remote>
<direction>
<spf>
<dkim>
<group>
<result>
<verdict>
<subject>
<info>
<ci>
<co>

Get_messagedata response format

<records> Value Description
<msg> element Details of a message between a local and a remote

Get_messagedata response records element

<msg> Format Description
<date> yyyy-mm-dd hh:mm:ss Time of message reception by LogiQ
<ip> 000.000.000.000 Source IP address (127.0.0.1 is outbound)
<local> Email address local email address
<remote> Email address Remote email address
<direction> String “inbound”, “outbound”
<spf> SPF result from MTA “”,“none”, “pass”, “fail”
<dkim> DKIM result from MTA “”,“none”,“pass”,“fail”
<group> String The domain name excluding the @ and .TLD
<result> CODE.SUBCODE See below
<verdict> String “”, Verdict string from communication infrastructure
<subject> String Communication subject
<info> String Information string from communication infrastructure
<ci> Numeric Number of communications from remote communicator
<co> Numeric Number of communications to remote communicator

Get_messagedata response msg element

<CODE>

Meaning

GLOBAL_WL    

The relationship is known to be trusted

SYSTEM_WL    

The relationship is known to be trusted

SHARED_WL    

The relationship is known to be trusted

AUTO_WL      

The relationship is known to be trusted

DOMAIN_WL    

The remote domain is valid

USER_WL      

The relationship has been validated by the administrator

UNKNOWN      

The relationship is currently unknown

SYSTEM_BL    

The relationship is known to be untrusted

DOMAIN_BL    

The remote domain is known to be untrusted

USER_BL      

The relationship is untrusted by the administrator

DENY         

The query was rejected

ERROR 

The query resulted in an error

LogiQ query response code

<SUBCODE> Meaning
UNKNOWN The local and remote have not previously communicated
CONFIRMED The local and remote communication has reached a trusted level
EXACT The local and remote communication is validated
EXISTS The local and remote communication is validated
PARTIAL The local and remote communication is partially validated
EXCLUDED The administrator has placed the domain in the exclusion list
OVERLIMIT The local has been sending messages at such a rate that it appears to be compromised.
SUSPICIOUS This code may be used in the future to signify the transaction should be checked by the user.

LogiQ query response sub code


<records>
<msg>
<date>2012-09-05 17:30</date>
<ip>127.0.0.1</ip>
<local>angela@acme.com</local>
<remote>steve@remote.com</remote>
<direction>outbound</direction>
<spf></spf>
<dkim></dkim>
<group>acme</group>
<result>UNKNOWN.EXISTS</result>
<verdict></verdict>
<subject></subject>
<info></info>
</msg>
<msg>
<date>2012-09-05 17:24</date>
<ip>193.2.3.4</ip>
<local>steve@remote.com</local>
<remote>fred@acme.com</remote>
<direction>inbound</direction>
<spf>pass</spf>
<dkim></dkim>
<group>default</group>
<result>AUTO_WL.EXACT</result>
<verdict>spam</verdict>
<subject>hi there</subject>
<info>size:345</info>
<ci>54</ci>
<co>22</co>
</msg>
</records>

Example – Get_messagedata XML output

TSV data format


The response consists of several lines containing tab separated values.

download

Note: the time fields in TSV format are compatible with spread sheets.

Tab stop Format Description
1 YYYY-MM-DD HH:MM <date>
2 000.000.000.000 <ip>
3 Email address <local>
4 Email address <remote>
5 “inbound”, “outbound” <direction>
6 String <group>
7 see above <result>
8 String <verdict>
9 String <subject>
10 String <spf>
11 String <dkim>
12 String <info>
13 Numeric:Numeric <ci>:<co>