Introduction

Welcome to the Secure Practice API by Secure Practice.

Version: 1.10 Updated: 13.10.2023

The Secure Practice API is a REST API to integrate with partner and customer platforms, and third party vendors.

It uses predictable, resource-oriented URLs, and is accessed by making HTTPS requests to a specific version of endpoint URLs.

GET, POST, PUT, PATCH, and DELETE methods dictate how you interact with the available resources in an idempotent manner (where possible), and HTTP response codes are used to indicate success or failure.

Authentication

Example request with authentication:

curl -X GET "https://api.mailrisk.com/v1/emails" -u $KEY:$SECRET

API calls are authenticated with HTTP Basic authentication.

This means that your API calls may add an Authorization header, which contains the keyword 'Basic' before a valid API access token, which is generated from a base64 encoded string of API key and secret values, joined by a colon (:).

Your personal API Key and API Secret values are retrieved from activating API access in the customer portal: https://manage.securepractice.co/settings/security

Authorization: Basic base64($KEY:$SECRET)

Pagination

Example request to retrieve items number 51 through 100:

curl -X GET "https://api.mailrisk.com/v1/emails?limit=50&page=2" -u $KEY:$SECRET    

Collection methods are automatically paginated, based on standard values.

Ordering of items is only available where explicitly stated in the documentation.

Partner collections

Example request to retrieve items available through partnership:

curl -X GET "https://api.mailrisk.com/v1/emails?partner=true" -u $KEY:$SECRET    

Define if you are requesting collections based on partnership status, i.e. across tenants for which you are a security partner.

Responses

curl -X GET "https://api.mailrisk.com/v1/email/9999999999" -u $KEY:$SECRET    

Example error response:

{
    "result" : "error",
    "code" : "404",
    "count" : "0",
    "data" : {
        "message" : "The requested resource could not be found."
    }
}

All response bodies are, unless otherwise stated, encoded in JSON, including failed requests along with their HTTP status code and error message. Notary exceptions include exported email messages in .eml format, as well as email attachments in their original format.

Status codes are also included in the returned JSON object, along with either success or error as result. A more detailed error message could be included in the message property of the data object.

See the full list of status codes for more information.

Rate limits

By default, each account is rate limited to a specific number requests per minute. The X-RateLimit-Limit-Remaining header will be returned upon any request, indicating how many requests remain.

If the rate limit is overrun, any requests will return HTTP error 429, as described in status codes, and the Retry-After header will be included to indicate how many seconds until new requests are made available, including the X-RateLimit-Reset with a timestamp to tell exactly when this happens.

Events

MailRisk analysis is a dynamic and asynchronous process, using input from both end users, data correlations, automated scans, and security analysts. Updates to emails, threats and other objects may occur at any time.

Listening to events will provide accurate information, as opposed to performing repeated queries on listing threats and emails.

The following flowchart describes which events may be triggered through the following API endpoint (see full size), which are denoted by simple rectangles:

Note that there are no guarantees about the timing of any of the events.

List events

GET /v1/events

Example request:

curl -X GET "https://api.mailrisk.com/v1/events?after=1631878200" -u $KEY:$SECRET    

Example response:

{
    "code" : 200,
    "result" : "success",
    "count" : 2,
    "page" : 1,
    "data" : [
        {
            "event" : "metadata_received",
            "email_id" : 1,
            "created_at" : "2021-09-17 13:30:50"
        },
        {
            "event" : "feedback_requested",
            "email_id" : 1,
            "created_at" : "2021-09-17 13:31:00"
        },
        {
            "event" : "contents_received",
            "email_id" : 1,
            "created_at" : "2021-09-17 13:31:01"
        },
        {
            "event" : "risk_changed",
            "email_id" : 1,
            "created_at" : "2021-09-17 13:48:19"
        },
        {
            "event" : "feedback_given",
            "email_id" : 1,
            "created_at" : "2021-09-17 13:48:42"
        }
    }
}

Retrieves events from the user's company (or partner) access level.

HTTP request

GET /v1/events

Query parameters

Returns

Returns an array of events, sorted by ID (based on UTC creation time) in ascending order (unless direction parameter is set otherwise), and may be paginated.

Possible event types relating to emails include metadata_received, contents_received, email_reported, email_revoked, feedback_requested, feedback_given, feedback_cancelled, and risk_changed.

Returned event objects do not contain any additional information apart from the IDs of any referenced object(s), and their timestamp.

Emails

List emails

GET /v1/emails

Example request:

curl -X GET "https://api.mailrisk.com/v1/emails?limit=2&page=1&order=id&direction=desc" -u $KEY:$SECRET    

Example response:

{
    "code" : 200,
    "result" : "success",
    "count" : 2,
    "page" : 1,
    "data" : [
        {
            "id": 2,
            "company_id": 1,
            "message_id" : "A0D06843A6834766B73E5AFE6E30DCC1@dmz2.loc",
            "size_bytes" : 293430,
            "subject" : "You've got a new document",
            "from_email" : "noreply@alerts-drpbox.com",
            "from_name" : "Ɗropbox",
            "reply_to": "dimallen412@gmail.com <dimallen412@gmail.com>",
            "spam_score": 0,
            "spf" : "none",
            "originating_ip" : "192.210.198.8",
            "links_count" : 2,
            "attachments_count" : 1,
            "reporter_domain" : "securepractice.co",
            "feedback_requested" : false,
            "feedback_provided" : false,
            "reported_risk" : 2,
            "category" : null,
            "risk" : null,
            "risk_source" : null,
            "sent_at" : "2022-01-06 12:27:46",
            "checked_at" : "2022-01-06 12:40:50",
            "reported_at" : "2022-01-06 12:41:01",
            "assessed_at": null,
            "content_status": "unknown",
        },
        {
            ...
        }
    }
}

Retrieves emails.

HTTP request

GET /v1/emails

Query parameters

Returns

Returns emails objects as an array.

Submit an RFC/822 email file

POST /v1/emails

Example request:

curl -X POST "https://api.mailrisk.com/v1/emails" -u $KEY:$SECRET \
    -H "Content-Type: multipart/form-data"
    -F "email=@LOCALFILE"

Example response:

{
    "code" : "201",
    "result" : "success",
    "data" : {
        "id" : 1
    }
}

Submit an email file formatted according to RFC/822 (.eml), for analysis.

This POST method is idempotent, meaning that if the email has already been submitted by the same user, the previous email object is returned without adding a new instance.

HTTP request

POST /v1/emails

Body parameters

Returns

Returns the inserted email ID if a valid email file was provided. Returns an error otherwise.

Get an email

GET /v1/emails/:id

Example request

curl -X GET "https://api.mailrisk.com/v1/emails/1" -u $KEY:$SECRET    

Example response:

{
    "code" : "200",
    "result" : "success",
    "data" : {
        "message_id" : "A0D06843A6834766B73E5AFE6E30DCC1@dmz2.loc",
        "size_bytes" : 293430,
        "subject" : "You've got a new document",
        "from_email" : "noreply@alerts-drpbox.com",
        "from_name" : "Ɗropbox",
        "reply_to": "dimallen412@gmail.com <dimallen412@gmail.com>",
        "spam_score": 0,
        "spf" : "none",
        "originating_ip" : "192.210.198.8",
        "company_id": 1,
        "reporter_domain" : "securepractice.no",
        "reported_risk" : 2,
        "category" : "phishing",
        "risk" : 3,
        "feedback_requested": 0,
        "sent_at" : "2022-01-06 12:27:46",
        "checked_at" : "2022-01-06 12:40:50",
        "reported_at" : "2022-01-06 12:41:01",
        "assessed_at": null,
        "headers" : [
            { "mime-version" : "1.0" },
            { "reply-to" : "dimallen412@gmail.com <dimallen412@gmail.com>" },
            ...
        ],
        "links" : [],
        "attachments" : [
            {
                "filename" : "Invoice_917569811.doc",
                "extension" : "doc",
                "content_type" : "application/msword",
                "content_id" : null,
                "is_inline" : false,
                "size_bytes" : "165169",
                "md5_hash" : "2a855fe640146d4e6b3115055e038a35",
                "sha1_hash" : "a6bc67f2a61f7c6f6d64d8d6df2b3b4b2607d0fd",
                "sha256_hash" : "98d73054cad69142842301edf9adfd19e3e46baa05146dc8df818bced711f835",
                "last_modified_at" : "2022-01-06 10:01:40",
                "download_screenshot" : null
                "download_file" : "https://api.mailrisk.com/v1/emails/1/attachments/1/export",
            },
            ...
        ],
        "content_status": "received",
        "download_screenshot" : "https://api.mailrisk.com/v1/emails/1/screenshot"
        "download_redacted" : "https://api.mailrisk.com/v1/emails/1/export",
        "download_original" : "https://api.mailrisk.com/v1/emails/1/export/original",        
        "assessments" : [
            {
                "risk": 3,
                "category": "phishing",
                "confidence": 0.9,
                "source": "signature",
                "source_id": 2,
                "assessed_at": "2022-01-06 12:55:32"
            },
            {
                "risk": 2,
                "category": null,
                "confidence": 0.4,
                "source": "user",
                "source_id": 1,
                "assessed_at": "2022-01-06 12:41:01"
            }
        ]
    }
}

Retrieve a specific email with the given ID.

The reported_at field represents when the user has actively clicked the "suspicious" or "spam" buttons in the MailRisk add-in, or when feedback has been requested. If neither of these are the case, the value will be null.

The reporter_email field will be null until a risk assessment value has been associated with the email, in order to avoid unnecessary distribution of personal data.

The content_status field value indicates the state of receiving email data, and will be set to received when the entire RFC/822 email has been received successfully. Until then, the value may be either pending when a transfer is in progress, or missing if a transfer was initated but subsequently aborted due to either the user closing the add-in before transfer has been completed, or network connectivity has otherwise been lost during transfer.

Finally, for customers having configured email contents retrieval only after the reported_at field has been set as described above, the content_status field's value is initiated as unknown upon receipt of metadata, and kept at this value until any transfer has been initated due to user interaction, which is unfortunately impossible to predict.

HTTP request

GET /v1/emails/:id

Returns

Returns a JSON formatted email object if a valid email was provided. Returns an error otherwise.

Get attachments metadata

GET /v1/emails/:id/attachments

Example request

curl -X GET "https://api.mailrisk.com/v1/emails/1/attachments" -u $KEY:$SECRET    

Example response:

{
    "code" : "200",
    "result" : "success",
    "data" : {
        [
            {
                "filename" : "Invoice_917569811.doc",
                "extension" : "doc",
                "content_type" : "application/msword",
                "content_id" : null,
                "is_inline" : false,
                "size_bytes" : "165169",
                "md5_hash" : "2a855fe640146d4e6b3115055e038a35",
                "sha1_hash" : "a6bc67f2a61f7c6f6d64d8d6df2b3b4b2607d0fd",
                "sha256_hash" : "98d73054cad69142842301edf9adfd19e3e46baa05146dc8df818bced711f835",
                "last_modified_at" : "2022-01-06 10:01:40",
                "download_screenshot" : null
                "download_file" : "https://api.mailrisk.com/v1/emails/1/attachments/1/export",
            },
            ...
        ]
    }
}

Retrieve metadata for attachments to a specific email with the given ID.

HTTP request

GET /v1/emails/:id/attachments

Returns

Returns a JSON formatted array of attachments data if a valid email was provided. Returns an error otherwise.

Get links metadata

GET /v1/emails/:id/links

Example request

curl -X GET "https://api.mailrisk.com/v1/emails/1/links" -u $KEY:$SECRET    

Example response:

{
    "code" : "200",
    "result" : "success",
    "data" : {
        [
            {
              "url": "https://gzq-f.de/82nayb37sb3a/",
              "text": "https://www.skatteetaten.no/person/",
              "hostname": "gzq-f.de"
            },
            ...
        ]
    }
}

Retrieve metadata for links to a specific email with the given ID.

Use request GET /v1/tools/hostinfo/:hostname to obtain more info on each specific hostname, if needed.

HTTP request

GET /v1/emails/:id/links

Returns

Returns a JSON formatted array of links data if a valid email was provided. Returns an error otherwise.

Download RFC/822

GET /v1/emails/:id/export/original

Example request

curl -X GET "https://api.mailrisk.com/v1/emails/1/export/original" -u $KEY:$SECRET    

Response will return the original email in .eml format.

Content-Type: message/rfc822
Content-Disposition: attachment; filename="You've got a new document.eml"
Content-Length: 71413

Retrieve a specific email with the given ID in its original RFC/822 format.

HTTP request

GET /v1/emails/:id/export/original

Returns

Returns an .eml file if a valid email ID was provided. Returns an error otherwise.

HTTP headers in the response will set Content-Type to message/rfc822, Content-Disposition and Content-Length (size in bytes), to describe the returned .eml file.

Download email screenshot

GET /v1/emails/:id/screenshot

Example request

curl -X GET "https://api.mailrisk.com/v1/emails/1/screenshot" -u $KEY:$SECRET    

Response will return a screenshot of the email in the PNG format.

Content-Type: image/png
Content-Disposition: attachment; filename="screenshot.png"
Content-Length: 91993

Retrieve a screenshot of an email's HTML contents with a given ID.

HTTP request

GET /v1/emails/:id/screenshot

Returns

Returns a PNG image file if a valid email ID was provided, provided that we have been able to generate it yet. Returns 204 if email is still being processed for screenshot (please try again a bit later). Returns an error otherwise.

HTTP headers in the response will include Content-Type (image/png), Content-Disposition (including filename) and Content-Length (size in bytes), to describe the returned image file.

Download attachment

GET /v1/emails/:id/attachments/:id/export

Example request

curl -X GET "https://api.mailrisk.com/v1/emails/1/attachments/1/export" -u $KEY:$SECRET    

Response will return the original attachment file in its original format, which is available along with filename in the response HTTP headers.

Content-Type: image/png
Content-Disposition: attachment; filename="xzgof.png"
Content-Length: 1413

Retrieve a specific attachment from an email with each their given IDs.

HTTP request

GET /v1/emails/:id/attachments/:id/export

Returns

Returns a file if a valid email ID and attachment ID was provided, obtain a valid download link via GET /v1/emails/:id. Returns an error otherwise.

HTTP headers in the response will include Content-Type (with original MIME type), Content-Disposition (including filename) and Content-Length (size in bytes), to describe the returned file.

Download attachment screenshot

GET /v1/emails/:id/attachments/:id/screenshot

Example request

curl -X GET "https://api.mailrisk.com/v1/emails/1/attachments/1/screenshot" -u $KEY:$SECRET    

Response will return a screenshot of the attachment in the PNG format.

Content-Type: image/png
Content-Disposition: attachment; filename="screenshot.png"
Content-Length: 91993

Retrieve a screenshot from an attachment with a given ID, currently we support PDF files and only the first page.

HTTP request

GET /v1/emails/:id/attachments/:id/screenshot

Returns

Returns a PNG image file if a valid email and attachment IDs were provided, provided that we have been able to generate it yet. Returns 204 if attachment is still being processed for screenshot (please try again a bit later). Returns an error otherwise.

HTTP headers in the response will include Content-Type (image/png), Content-Disposition (including filename) and Content-Length (size in bytes), to describe the returned image file.

Provide risk assessment for an email

POST /v1/emails/:id/risk

Example request:

curl -X POST "https://api.mailrisk.com/v1/emails/1/risk" -u $KEY:$SECRET \
    -H "Content-Type: application/x-www-form-urlencoded" \
    -d risk=3 \
    -d category="phishing" \
    -d source="manual" \
    -d data="{}"

Example response:

{
    "code" : "201",
    "result" : "success",
    "data" : {
        "id" : 1
    }
}

Provide risk assessment for a specific email with the given ID.

If the email is correlated with other emails, those emails may receive the same risk value as well, given sufficient assessment/correlation confidence.

If the risk source is manual (i.e. from an analyst), this value will probaly override any other risk value provided.

This method is not idempotent, meaning that every request will add a new risk assessment entry in the database.

HTTP request

POST /v1/emails/:id/risk

Body parameters

Returns

Returns HTTP 201 if the resource was created. Returns an error otherwise.

Get (proposed) feedback for email

GET /v1/emails/:id/feedback

Example request:

curl -X GET "https://api.mailrisk.com/v1/emails/1/feedback" -u $KEY:$SECRET

Example response:

{
    "code" : "200",
    "result" : "success",
    "data" : {
        "requested_at" : "2022-06-19 10:55:41",
        "responded_at" : null,
        "text" : "We have examined the email, and this appears to be harmless.",
        "locale" : "en-US"
    }
}

Return a feedback message for a specific email with the given ID.

If the reporter has already received such feedback, the response will include the actual message which was sent.

Otherwise, the responded_at variable will be null and the text variable will include a relevant suggestion for locale based on the user's language, as set in their profile.

It is highly recommended to ensure that a risk assessment has been performed on the given email before invoking this method, in order to obtain a more relevant feedback proposal. If a category is provided in addition to risk, the feedback proposal becomes even more relevant.

HTTP request

GET /v1/emails/:id/feedback

Returns

Returns a feedback text if a valid email ID was provided. Returns an error otherwise.

Send feedback message

POST /v1/emails/:id/feedback

Example request:

curl -X POST "https://api.mailrisk.com/v1/emails/1/feedback" -u $KEY:$SECRET \
    -H "Content-Type: application/x-www-form-urlencoded" \
    -d text="We have examined the email, and it looks like someone is trying to trick you here."

Example response:

{
    "code" : "201",
    "result" : "success",
    "data" : []
}

Provide a feedback message for a specific email with the given ID.

Unless explicitly skipped, the feedback message will be wrapped in an email template according to the system emails branding configuration set for the customer.

The email template will include some standard text based on the current risk assessment. For high risk emails, this text will say something about notifying IT if the user has already clicked links or attachments in the email. For medium and low risk emails, the text will include some tips for further investigation if the user is still uncertain.

All template text, except the input message, will be translated into the receiving user's language, as set in their profile.

HTTP request

POST /v1/emails/:id/feedback

Body parameters

Returns

Returns HTTP 201 if the resource was created. Returns an error otherwise.

Show user profile

POST /v1/emails/:id/user

Example request:

curl -X POST "https://api.mailrisk.com/v1/emails/1/user" -u $KEY:$SECRET \
    -H "Content-Type: application/x-www-form-urlencoded" \
    -d purpose="Need to quarantine email in Exchange"

Example response:

{
    "code" : "200",
    "result" : "success",
    "data" : {
        "mailbox_id" : "6e3b7c59-0fe7-4435-9203-2a714dd61379",
        "email" : "dummy@securepractice.no",
        "name" : null
    }
}

Return the identity of the user who reported an email, if available (depending on the organization's privacy settings).

Any mailbox_id available will represent the user's internal storage location on the email service.

name will contain the user's email profile name by default, but this could also have been edited by the user, or not be available at all (depending on the organization's privacy settings).

Please note that any requests for user info through this endpoint will be logged in particular.

HTTP request

POST /v1/emails/:id/user

Body parameters

Returns

Returns user info if a valid email ID was provided. Returns an error otherwise.

Signatures

List signatures

GET /v1/signatures

Example request:

curl -X GET "https://api.mailrisk.com/v1/signatures" -u $KEY:$SECRET    

Example response:

{
    "code" : 200,
    "result" : "success",
    "count" : 20,
    "data" : [
        {
          "id": 40,
          "title": "Spam surge from Example Inc.",
          "description": "Lately we've seen a surge in spam being sent from employees at Example Inc.",
          "category": "spam",
          "risk": 1,
          "tlp": "green",
          "priority": 5,
          "query": "header:to=\"*@mycompany.com*\" AND subject=\"Urgent: Get your \\\"free\\\" copy today\" AND (from_email=\"*@exampleinc.com*\" OR from_name=\"*Example Inc.*\") AND not(from_email=\"*@trusted.com\") AND sent>\"2021-01-01\""
        },
    ]
}

Retrieves signatures.

HTTP request

GET /v1/signatures

Query parameters

Returns

Returns signature objects as an array.

Add signature

POST /v1/signatures

Example request:

curl -X POST "https://api.mailrisk.local/v1/signatures" -u $KEY:$SECRET \
    -H "Content-Type: application/x-www-form-urlencoded" \ 
    -d title="Spam surge from Example Inc." \
    -d description="Lately we have seen a surge in spam being sent from employees at Example Inc." \
    -d category="spam" \
    -d risk=1 \
    -d tlp="green" \
    -d priority=5 \
    -d query="header:to=\"*@mycompany.com*\" AND subject=\"Urgent: Get your \\\"free\\\" copy today\" AND (from_email=\"*@exampleinc.com*\" OR from_name=\"*Example Inc.*\") AND not(from_email=\"*@trusted.com\") AND sent>\"2021-01-01\""

Example response:

{
  "result": "success",
  "code": 200,
  "data": {
    "id": 41,
    "title": "Spam surge from Example Inc.",
    "description": "Lately we've seen a surge in spam being sent from employees at Example Inc.",
    "category": "spam",
    "risk": 1,
    "tlp": "green",
    "priority": 5,
    "query": "header:to=\"*@mycompany.com*\" AND subject=\"Urgent: Get your \\\"free\\\" copy today\" AND (from_email=\"*@exampleinc.com*\" OR from_name=\"*Example Inc.*\") AND not(from_email=\"*@trusted.com\") AND sent>\"2021-01-01\""
  }
}

Add a signature by sending a JSON payload to the designated endpoint.

HTTP request

POST /v1/signatures

Signature body parameters

Query structure

Simple search example: subject = "Urgent: Get your copy today"

A search is structured on the form: Namespace:Property Comparator "Value"

For the header namespace arbitrary header names can be used as properties.

Advanced search example: header:to="*@mycompany.com*" AND subject="Urgent: Get your \"free\" copy today" AND (from_email="*@exampleinc.com*" OR from_name="*Example Inc.*") AND not(from_email="*@trusted.com") AND sent>"2021-01-01"

It is possible to combine simple searches in an advanced search using AND, OR, NOT() and properly placed parantheses to create sub expressions.

It is also possible to add the character * in order for the value to be a part of the whole value. Starts with: "value*" Ends with: "*value" Contains: "*value*" If the search starts or ends with * not relevant to the rules above, please prepend a slash: \*. If the search contains " please prepend a slash: \".

The properties sent and analyzed are dates. In the example above the > operator is used to show results after a specified date.

Returns

Returns a signature object if the request was successful. Otherwise an error is returned

Edit signature

PUT /v1/signatures/:id

Example request:

curl -X PUT "https://api.mailrisk.local/v1/signatures" -u $KEY:$SECRET \
    -H "Content-Type: application/x-www-form-urlencoded" \ 
    -d title="Spam surge from Example Inc." \
    -d description="Lately we have seen a surge in spam being sent from employees at Example Inc." \
    -d category="spam" \
    -d risk=1 \
    -d tlp="green" \
    -d priority=5 \
    -d query="header:to=\"*@mycompany.com*\" AND subject=\"Urgent: Get your \\\"free\\\" copy today\" AND (from_email=\"*@exampleinc.com*\" OR from_name=\"*Example Inc.*\") AND not(from_email=\"*@trusted.com\") AND sent>\"2021-01-01\""  

Example response:

{
  "result": "success",
  "code": 200,
  "data": {
    "id": 41,
    "title": "Spam surge from Example Inc.",
    "description": "Lately we have seen a surge in spam being sent from employees at Example Inc.",
    "category": "spam",
    "risk": 1,
    "tlp": "green",
    "priority": 5,
    "query": "header:to=\"*@mycompany.com*\" AND subject=\"Urgent: Get your \\\"free\\\" copy today\" AND (from_email=\"*@exampleinc.com*\" OR from_name=\"*Example Inc.*\") AND not(from_email=\"*@trusted.com\") AND sent>\"2021-01-01\""
  }
}

Edit a signature.

HTTP request

PUT /v1/signatures/:id

Body parameters

The same body parameter restrictions as documented for adding signatures apply for editing the signature.

Returns

Returns the signature object if the request was successful. Otherwise an error is returned

Metrics

Append ISO 8601 formatted dates to the request URL with the parameters from and to, in order to scope the request to a specific time span. Keep in mind that all timestamps are in UTC format, as already stated in the introduction.

If to is provided, from must also be provided. If to is otherwise not provided, the default time span is the last month.

Every response contains the selected time span in the range element, featuring the actual from and to the requests is calculated upon.

Email risk per unit

GET /v1/metrics/mailrisk

Example request:

curl -X GET "https://api.mailrisk.com/v1/metrics/mailrisk?from=2021-11-01" -u $KEY:$SECRET    

Example response:

{
  "result": "success",
  "code": 200,
  "data": {
    "range": {
      "from": "2021-11-01 00:00:00",
      "to": "2021-11-30 23:59:59"
    },
    "dataset": [
        "2021-11-01": {
          "unknown": 3,
          "low": 1,
          "medium": 1,
          "high": 0
        },
        "2021-11-02": {
          "unknown": 3,
          "low": 7,
          "medium": 15,
          "high": 9
        },
        ...
    ]
  }
}

Retrieve number of emails per risk level, per time unit.

HTTP request

GET /v1/metrics/mailrisk

Query parameters

Returns

Returns a list of maps, with one data point for each time unit in the selected period. Each item contains the count of emails on each risk level.

Email risk (total)

GET /v1/metrics/mailrisk/total

Example request:

curl -X GET "https://api.mailrisk.com/v1/metrics/mailrisk/total?from=2021-11-01&to=2021-11-30" -u $KEY:$SECRET    

Example response:

{
  "result": "success",
  "code": 200,
  "data": {
    "range": {
      "from": "2021-11-01 00:00:00",
      "to": "2021-11-30 23:59:59"
    },
    "unknown": 7,
    "low": 27,
    "medium": 180,
    "high": 102
  }
}

Retrieve aggregate count of emails per risk level (including unknown) in the selected period.

HTTP request

GET /v1/metrics/mailrisk/total

Query parameters

Returns

Returns a map of risk levels (unknown, low, medium, high), and the corresponding count of emails per risk level.

Email categories (total)

GET /v1/metrics/categories/total

Example request:

curl -X GET "https://api.mailrisk.com/v1/metrics/categories/total" -u $KEY:$SECRET    

Example response:

{
  "result": "success",
  "code": 200,
  "data": {
    "range": {
      "from": "2021-11-01 00:00:00",
      "to": "2021-11-30 23:59:59"
    },
    "harmless": 5,
    "spam": 22,
    "scam": 49,
    "phishing": 103,
    "malicious": 180,
    "malware": 9,
    "targeted": 1,
  }
}

Retrieve aggregate count of items by categorization.

HTTP request

GET /v1/metrics/categories/total

Query parameters

Returns

Returns a map of categories (harmless, spam, suspicious, scam, phishing, malicious, malware, targeted), and the corresponding count of emails per category.

Top email signatures

GET /v1/metrics/signatures

Example request:

curl -X GET "https://api.mailrisk.com/v1/metrics/signatures" -u $KEY:$SECRET    

Example response:

{
  "result": "success",
  "code": 200,
  "data": {
    "range": {
      "from": "2021-11-01 00:00:00",
      "to": "2021-11-30 23:59:59"
    },
    "dataset": [
      {
        "id": 2,
        "title": "Euro-Million Lottery",
        "count": 263,
        "category": "scam"
      },
      {
        "id": 1,
        "title": "Sign-in request blocked",
        "count": 193,
        "category": "phishing"
      },
      ...
    ]
  }
}

Retrieve the most matched signatures.

HTTP request

GET /v1/metrics/signatures

Query parameters

Returns

Returns a list of signatures, each with their id, title, category and the count of times they have been matched by emails duing the selected period.

Unique mailboxes

GET /v1/metrics/mailboxes

Example request:

curl -X GET "https://api.mailrisk.com/v1/metrics/mailboxes" -u $KEY:$SECRET    

Example response:

{
  "result": "success",
  "code": 200,
  "data": {
    "range": {
      "from": "2022-03-01 00:00:00",
      "to": "2022-03-31 23:59:59"
    },
    "dataset": [
      {
        "label": "2022-03-01",
        "count": 32
      },
      {...}
    ]
  }
}

Retrieve the number of unique mailboxes which MailRisk was used with, per time unit.

HTTP request

GET /v1/metrics/mailboxes

Query parameters

Returns

Returns a list of tuples, where the first indicate the time unit and the second the corresponding count of unique mailboxes.

Unique mailboxes (total)

GET /v1/metrics/mailboxes/total

Example request:

curl -X GET "https://api.mailrisk.com/v1/metrics/mailboxes/total" -u $KEY:$SECRET    

Example response:

{
  "result": "success",
  "code": 200,
  "data": {
    "range": {
        "from": "2022-03-01 00:00:00",
        "to": "2022-03-31 23:59:59"
    },
    "label": "mailboxes",
    "count": 1
  }
}

Retrieve the aggregated number of unique mailboxes which MailRisk was used with, in the selected period.

HTTP request

GET /v1/metrics/mailboxes/total

Query parameters

Returns

Returns the number of unique active users of MailRisk in the selected period.

Companies

The below endpoints allow partner organizations to maintain customer relationships programmatically, including required contact information, licensing status and various service configurations.

List companies

GET /v1/companies

Example request:

curl -X GET "https://api.mailrisk.com/v1/companies" -u $KEY:$SECRET    

Example response:

{
    "code" : 200,
    "result" : "success",
    "count" : 2,
    "data" : [
        {
            "id": 1,
            "firm" : "Secure Practice AS",
            "country" : "NO",
            "vat_id" : "NO919420197MVA"
        },
        {
            ...
        }
    }
}

Retrieves companies which customers of the partner account.

HTTP request

GET /v1/companies

Returns

Returns company objects as an array.

Add company

POST /v1/companies

Example request:

curl -X POST "https://api.mailrisk.com/v1/companies" -u $KEY:$SECRET \
    -H "Content-Type: application/x-www-form-urlencoded" \
    -d firm="Firm & co" \
    -d vat_id="NO233123543MVA"

Example response:

{
    "code" : "201",
    "result" : "success",
    "data" : {}
}

Provide company name, contact info and VAT registration number for a specific company with the given ID.

HTTP request

POST /v1/companies

Body parameters

Returns

Returns HTTP 201 if the resource was added. Returns an error otherwise.

Get company

GET /v1/companies/:id

Example request:

curl -X GET "https://api.mailrisk.com/v1/companies/1" -u $KEY:$SECRET    

Example response:

{
    "code" : 200,
    "result" : "success",
    "data" : {
        "id": 1,
        "firm": "Secure Practice AS",
        "postal_address": "Havnegata 9",
        "postal_code": "7010",
        "city": "Trondheim",
        "country": "NO",
        "vat_id": "NO919420197MVA",
        "domains": [
            "securepractice.co",
            "securepractice.no"
        ],
        "subscription": [
            "plan": "platinum"
            "count": 10,
            "rate": "1000",
            "currency": "NOK"
        ],
        "config": [
            "mailbox_provider": "o365",     
            "share_reported_emails_with_mailbox_provider": false,
            "analysis_responsible": "customer",
            "unassessed_email_retention_days": 365,
            "system_emails_brand": "default",
            "system_emails_reply_to": null                     
        ]
    }
}

Retrieves company info for a given customer of the partner account.

HTTP request

GET /v1/companies/:id

Returns

Returns a company data object.

Edit company

POST /v1/companies/:id

Example request:

curl -X POST "https://api.mailrisk.com/v1/companies/2" -u $KEY:$SECRET \
    -H "Content-Type: application/x-www-form-urlencoded" \
    -d firm="Firm & co" \
    -d country="NO"

Example response:

{
    "code" : "200",
    "result" : "success",
    "data" : {}
}

Provide company name, contact info and VAT registration number for a specific company with the given ID.

Properties may be updated individually without providing updated values for the other parameters.

HTTP request

POST /v1/companies/:id

Body parameters

Returns

Returns HTTP 200 if the resource was updated. Returns an error otherwise.

Edit configuration

PATCH /v1/companies/:id/config

Example request:

curl -X PATCH "https://api.mailrisk.com/v1/companies/1/config" -u $KEY:$SECRET \
    -H "Content-Type: application/x-www-form-urlencoded" \
    -d analysis_responsible="partner" \
    -d share_reported_emails_with_mailbox_provider="false" \
    -d unassessed_email_retention_days=0 \
    -d system_emails_reply_to="ithelpdesk@example.com"

Example response:

{
    "code" : "200",
    "result" : "success",
    "data" : {}
}

Provide configurations for a specific company with the given ID.

Properties may be updated individually without providing updated values for the other parameters.

HTTP request

PATCH /v1/companies/:id/config

Body parameters

Returns

Returns HTTP 200 if the resource was updated. Returns an error otherwise.

Edit subscription

POST /v1/companies/:id/subscription

Example request:

curl -X POST "https://api.mailrisk.com/v1/companies/2/subscription" -u $KEY:$SECRET \
    -H "Content-Type: application/x-www-form-urlencoded" \
    -d plan="platinum" \
    -d count=86 \
    -d rate="290" \
    -d currency="EUR"

Example response:

{
    "code" : "200",
    "result" : "success",
    "data" : {}
}

Provide licensing information for a specific company with the given ID.

HTTP request

POST /v1/companies/:id/subscription

Body parameters

Returns

Returns HTTP 200 if the resource was updated. Returns an error otherwise.

Add licensed domain

POST /v1/companies/:id/domains

Example request:

curl -X POST "https://api.mailrisk.com/v1/companies/2/domains" -u $KEY:$SECRET \
    -H "Content-Type: application/x-www-form-urlencoded" \
    -d domain="example.com"

Example response:

{
    "code" : "201",
    "result" : "success",
    "data" : {}
}

Adds a new web domain as valid to activate user licenses for a specific company with the given ID.

HTTP request

POST /v1/companies/:id/domains

Body parameters

Returns

Returns HTTP 201 if the resource was added. Returns an error otherwise.

Delete licensed domain

DELETE /v1/companies/:id/domains/:domain

Example request:

curl -X DELETE "https://api.mailrisk.com/v1/companies/2/example.com" -u $KEY:$SECRET

Example response:

{
    "code" : "200",
    "result" : "success",
    "data" : {}
}

Delete a web domain from activating user licenses for a specific company with the given ID.

HTTP request

DELETE /v1/companies/:id/domains/:domain

Returns

Returns HTTP 200 if the resource was deleted. Returns an error otherwise.

List users

Retrieves users.

GET /v1/companies/:id/users

Example request:

curl -X GET "https://api.mailrisk.com/v1/companies/:id/users?page=1&limit=20" -u $KEY:$SECRET    

Example response:

{
    "code" : 200,
    "result" : "success",
    "count" : 2,
    "data" : {
        "current_page": 1,
        "data": [
            {
                "id": 1,    
                "email": "john.doe@example.com",
                "firstname": "John",
                "lastname": "Doe",
                "mobile_prefix": "+47",
                "mobile": "99999999",
                "unit": "Norway > Service",
                "locale": "en-US",
            },
            {
                "id": 2,
                "email": "jane.doe@example.com",
                "firstname": "Jane",
                "lastname": "Doe",
                "mobile_prefix": "+47",
                "mobile": "99999999",
                "unit": "Norway > Administration",
                "locale": "nb-NO",
            },
            {
                ...
            }
        ],
        "from": 1,
        "last_page": 1,
        "per_page": 20,
        "to": 2,
        "total": 2
    }
}

Retrieves users in the specified company.

HTTP request

GET /v1/companies/:id/users

Query parameters

Returns

Returns user objects as an array.

Add or update users

POST /v1/companies/:id/users

Example request:

curl -X POST "https://api.mailrisk.com/v1/companies/2/users" -u $KEY:$SECRET \
    -H "Content-Type: application/x-www-form-urlencoded" \
    -d email="example@securepractice.co" \
    -d firstname="Jane" \
    -d lastname="Doe" \
    -d mobile_prefix="+47" \
    -d mobile="99999999" \
    -d org_unit="Norway" \
    -d sub_unit="Administration" \
    -d locale="nb-NO"

Example response:

{
    "code" : "201",
    "result" : "success",
    "data" : {
        "id": 2,
        "email": "jane.doe@example.com",
        "firstname": "Jane",
        "lastname": "Doe",
        "mobile_prefix": "+47",
        "mobile": "99999999",
        "unit": "Norway > Administration",
        "locale": "nb-NO",
    }
}

Adds a new user, or updates an existing user, as enabled for employee portal access at a specific company with the given ID.

Note that any domain name used in the email address provided for a user, must beforehand be added as a licensed domain for use on the specific company.

Properties may be updated individually without providing updated values for the other parameters.

HTTP request

POST /v1/companies/:id/users

Body parameters

Returns

Returns HTTP 201 if a new resource was added, or HTTP 200 if an existing was successfully updated. Returns an error otherwise.

Tools

Hostname info

GET /v1/tools/hostinfo

Example request:

curl -X GET "https://api.mailrisk.com/v1/tools/hostinfo/click.email.microsoftonline.com" -u $KEY:$SECRET    

Example response:

{
    "code" : 200,
    "result" : "success",
    "data" : {
        "hostname" : "click.email.microsoftonline.com",
        "domain": "microsoftonline.com",
        "tld" : "com",
        "ip": [
            {
                "ip": "13.111.42.7",
                "latitude": "39.76780",
                "longitude": "-86.15840",
                "postal_code": "46204",
                "city": "Indianapolis",
                "country_code": "US",
                "country": "United States",
                "region_code": "IN",
                "region": "Indiana",
                "timezone": "America/Indiana/Indianapolis",
                "timestamp": "2021-06-12 04:27:07"
            }
        ],
        "whois": {
            "is_registered": true,
            "registered_at": "2002-07-09",
            "changed_at": "2021-06-07",
            "expires_at": "2022-07-09",
            "retrieved_at": "2021-06-12 04:27:03"
        }
    }

}

Retrieves info about a given hostname (domain with any subdomains), including basic WHOIS information where possible.

IP-address history for particular hostname is retrieved (if available), based on our previous records (up to 10 records).

HTTP request

GET /v1/tools/hostinfo/:hostname

Returns

Returns host info object as an array.

Status codes

The MailRisk API responds with the following HTTP status codes: