SpamOverflow

Email Service

/customers/{customer_id}/emails

List all submitted emails for a given customer.

Returns a list of all emails submitted for the given customer id with the optional filters applied. The limit and offset parameters are used for stepping through blocks of emails / paging through the results. If the offset is greater than the amount of entries that exist then an empty array should be returned. If there are no emails associated with the given customer id, an empty array should be returned. All other parameters are used to filter the results and should be applied before the limit and offset parameters. e.g. if 300 emails exists and 200 are labelled as malicious then a request of limit=100 and only_malicious=true should return 100 emails. If limit=100, only_malicious=true, and offset=200 then the response should be 0 emails (an empty array). **The filters are additive and as such if the filter is not in the request then it should not be applied. e.g. if only_malicious=true is not in the request then all emails should be returned regardless of their malicious status. The exception to this is the limit and offset parameters which have defaults which are applied if they are not in the request.**


Curl Request Example

curl -X GET \
 -H "Accept: application/json" \
 "http://email.api.spamoverflow.com/api/v1/customers/{customer_id}/emails?limit=20&offset=0&start=2024-02-21T13:10:05Z&end=2024-02-21T14:10:05Z&from=no-reply@uq.edu.au&to=support@uq.edu.au&state=scanned&only_malicious=true"

Path parameters

Name Description
customer_id*
String
The customer identifier is a UUIDv4.
Required

Query parameters

Name Description
limit
Integer
Returns only this many results, 0 < limit <= 1000. **Default is 100**.
offset
Integer
Skip this many results before returning, 0 <= offset. **Default is 0**.
start
Date (date-time)
Only return emails submitted from this date. The date should be in RFC3339 format.
end
Date (date-time)
Only return emails submitted before this date. The date should be in RFC3339 format.
from
String (email)
Only return emails submitted from this email address. The email address should be in the format of user@domain.
to
String (email)
Only return emails submitted to this email address. The email address should be in the format of user@domain.
state
String
Only return emails with this state. The state should be one of 'pending', 'scanned', 'failed'.
only_malicious
Boolean
Only return emails that have been flagged as malicious.

Responses

/customers/{customer_id}/emails/{id}

Get information for a particular email.

Returns a representation of an email for a customer with the status of the scan and its result.


Curl Request Example

curl -X GET \
 -H "Accept: application/json" \
 "http://email.api.spamoverflow.com/api/v1/customers/{customer_id}/emails/{id}"

Path parameters

Name Description
customer_id*
String
The customer identifier is a UUIDv4.
Required
id*
String
The email identifier that was returned when the request was created.
Required

Responses

/customers/{customer_id}/emails

Post a new email scan request.

If the customer account does not exist, it will be created. The customer's ID identifies if the request must have a high priority or not, see the description in the parameters section.


Curl Request Example

curl -X POST \
 -H "Accept: application/json" \
 -H "Content-Type: application/json" \
 "http://email.api.spamoverflow.com/api/v1/customers/{customer_id}/emails" \
 -d '{
  "metadata" : {
    "spamhammer" : "1|14"
  },
  "contents" : {
    "subject" : "Important information about your account.",
    "from" : "support@uq.edu.au",
    "to" : "no-reply@uq.edu.au",
    "body" : "Dear customer,\nWe have noticed some suspicious activity on your account. Please click [here](https://scam-check.uq.edu.au?userId=uqehugh3) to reset your password."
  }
}'

Path parameters

Name Description
customer_id*
String
The customer identifier is a UUIDv4 where the first 4 characters represent the customer type. Customers with 1111####-####-####-####-############ are to be treated as high priority while all other valid UUIDv4's are to be treated as standard priority.
Required

Body parameters

Name Description
body *

Responses

/customers/{customer_id}/reports/actors

Get malicious senders of emails.

Returns a list of all senders/actors identified as sending at least one email that is flagged as malicious. This report should be kept up-to-date with a maximum of five minutes delay.


Curl Request Example

curl -X GET \
 -H "Accept: application/json" \
 "http://email.api.spamoverflow.com/api/v1/customers/{customer_id}/reports/actors"

Path parameters

Name Description
customer_id*
String
The customer identifier is a UUIDv4.
Required

Responses

/customers/{customer_id}/reports/domains

Get the domains that appeared in malicious emails.

Returns a report consisting of the link domains found in malicious emails for the given customer. This report should be kept up-to-date with a maximum of five minutes delay.


Curl Request Example

curl -X GET \
 -H "Accept: application/json" \
 "http://email.api.spamoverflow.com/api/v1/customers/{customer_id}/reports/domains"

Path parameters

Name Description
customer_id*
String
The customer identifier is a UUIDv4.
Required

Responses

/customers/{customer_id}/reports/recipients

Get users who have received malicious emails.

Returns a list of all recipients who have received at least one email message that is identified as malicious. This report should be kept up-to-date with a maximum of five minutes delay.


Curl Request Example

curl -X GET \
 -H "Accept: application/json" \
 "http://email.api.spamoverflow.com/api/v1/customers/{customer_id}/reports/recipients"

Path parameters

Name Description
customer_id*
String
The customer identifier is a UUIDv4.
Required

Responses

/health

Query the health of the service.

The health endpoint is useful for determining whether an instance is still healthy. This can help if you are configuring auto-scaling groups or load balancers. We do not specify the response payload for this endpoint, however you may find it useful to return a more detailed status of your system. For example: https://eloquentcode.com/rest-api-design-health-check-endpoint


Curl Request Example

curl -X GET \
 "http://email.api.spamoverflow.com/api/v1/health"

Responses