guide

How to encode data before making a submission via the API

When sharing data via the API, some users are experiencing issues encoding data. Where an email text attachment is included (likely to include strange characters), JSON is not always encoded correctly. To help we have provided step-by-step guidance on how to send RAW email source code using a BASH or PHP script.

by The Spamhaus TeamNovember 30, 20232 minutes reading time

In this guide

First Steps
Using BASH script to send submission
Using PHP script to send submission

Jump to

First Steps

First you will need to find the RAW email source code from your email client. You can find step-by-step guidance on how to access email source code for the three most popular email clients (Apple, Gmail and Outlook) here.

For the following examples, we assume the email source code file is saved as email.txt

Using BASH script to send submission

Install jq as a prerequisite

jq is a lightweight and flexible command-line JSON processor.

Installation instructions for jq vary depending on your operating system and are available at: https://jqlang.github.io/jq/download/

Copy and paste the following text into a file named send.sh in the same folder as where you saved your email – remember to make the necessary replacements e.g. your authentication token.

#!/bin/bash

# your API token here
token="aaaaaabbbbbcccccddddeeeeffff"

# set variables for 'reason', 'source' and 'threat_type' fields
threat="spam"
reason="this email contains a virus"
source=$(cat email.txt)

# build the json
json_data=$(jq  -n  --arg threat "$threat" --arg reason "$reason" --arg source "$source" \
'{
	"threat_type": $threat,
	"reason": $reason,
	"source": {
		"object": $source
	}
}')

# use CURL to send the json
curl -s -H 'Content-Type: application/json' \
     -H "Authorization: Bearer $token" \
     --data-raw "$json_data" \
     https://submit.spamhaus.org/portal/api/v1/submissions/add/email

Execute the script: bash send.sh

Using PHP script to send submission

Install the PHP CLI interpreter according to your operating system. Note this might already be installed.
Copy and paste the following text into a file named send.php in the same folder where you saved your email - remember to make the necessary replacements e.g. your authentication token.

<?php

// your API token here
$token = "aaaaabbbbbccccddddeeefff";

// set variables for 'reason', 'source' and 'threat_type' fields
$threat = "spam";
$reason = "this email contains a virus";
$source = file_get_contents("email.txt");

// build the JSON
$data = [
	"threat_type" => $threat,
	"reason" => $reason,
	"source" => [
	    "object" => $source
	]
];

// encode the data as JSON
$json_data = json_encode($data);

// use cURL to send the JSON
$ch = curl_init("https://submit.spamhaus.org/portal/api/v1/submissions/add/email");

curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
	'Content-Type: application/json',
	"Authorization: Bearer $token"
]);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, $json_data);
$response = curl_exec($ch);
curl_close($ch);

echo  $response;

Finally execute the script: php send.php