Form validation

Documentation

This documentation gives you a step-by-step introduction to server-side form validation via the API. It covers the request structure, the response format, and ready-to-use examples for your own projects.

The API checks form data through the scan endpoint. Send `sender`, `recipient`, `subject`, and `message` together with the three X-Spam headers.

Request data

Send each form submission server-side to the scan endpoint. The result is calculated from content, matches, and sender data.

Field	Required	Description
`sender`	Yes	Sender email address.
`recipient`	Yes	Target address or mailbox of the form.
`subject`	Yes	Request subject.
`message`	Yes	Message body or form content.

Response data

The API returns the spam score, verdict, and matched keywords. If `verdict = blocked`, stop processing the form.

code, verdict, score, threshold
matched_keywords, message_id, note

PHP Example

Example using the Laravel Http client. Use it in a controller or service before sending email.

Insert in: app/Http/Controllers/ContactController.php (or custom service in app/Services/SpamCheckService.php)



use Illuminate\Support\Facades\Http;

$response = Http::timeout(10)
    ->acceptJson()
    ->withHeaders([
        'X-Spam-Username' => 'dein-benutzername',
        'X-Spam-Password' => 'dein-passwort',
        'X-Spam-ApiKey' => 'dein-api-key',
    ])
    ->post('https://antispam.example.com/api/v1/scan', [
        'sender' => 'info@example.com',
        'recipient' => 'kontakt@example.com',
        'subject' => 'Anfrage über das Kontaktformular',
        'message' => 'Hallo, ich interessiere mich für Ihr Angebot.',
    ]);

if ($response->json('verdict') === 'blocked') {
    // Spam erkannt: Formular nicht weiterverarbeiten.
}

JavaScript Example

Example for a custom frontend or SPA. The check should still be enforced server-side.

Insert in: resources/js/app.js (or in your frontend component)

const response = await fetch('https://antispam.example.com/api/v1/scan', {
  method: 'POST',
  headers: {
    'Accept': 'application/json',
    'Content-Type': 'application/json',
    'X-Spam-Username': 'dein-benutzername',
    'X-Spam-Password': 'dein-passwort',
    'X-Spam-ApiKey': 'dein-api-key',
  },
  body: JSON.stringify({
    sender: 'info@example.com',
    recipient: 'kontakt@example.com',
    subject: 'Anfrage über das Kontaktformular',
    message: 'Hallo, ich interessiere mich für Ihr Angebot.',
  }),
});

const result = await response.json();

if (result.verdict === 'blocked') {
  // Nachricht als Spam behandeln.
}

cURL Example

Useful for tests, Postman-like workflows, or direct integrations.

Run in: Terminal / Shell

curl -X POST "https://antispam.example.com/api/v1/scan" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "X-Spam-Username: dein-benutzername" \
  -H "X-Spam-Password: dein-passwort" \
  -H "X-Spam-ApiKey: dein-api-key" \
  -d '{
    "sender": "info@example.com",
    "recipient": "kontakt@example.com",
    "subject": "Anfrage über das Kontaktformular",
    "message": "Hallo, ich interessiere mich für Ihr Angebot."
  }'

WordPress: Contact Form 7

Example showing how to validate a submission and prevent mail delivery when spam is detected.

Insert in: wp-content/themes/YOUR-CHILD-THEME/functions.php (alternatively own plugin)



add_action('wpcf7_before_send_mail', function ($contact_form) {
    $submission = WPCF7_Submission::get_instance();

    if (! $submission) {
        return;
    }

    $data = $submission->get_posted_data();

    $response = wp_remote_post('https://antispam.example.com/api/v1/scan', [
        'timeout' => 10,
        'headers' => [
            'Accept' => 'application/json',
            'Content-Type' => 'application/json',
            'X-Spam-Username' => 'dein-benutzername',
            'X-Spam-Password' => 'dein-passwort',
            'X-Spam-ApiKey' => 'dein-api-key',
        ],
        'body' => wp_json_encode([
            'sender' => sanitize_email($data['your-email'] ?? ''),
            'recipient' => get_option('admin_email'),
            'subject' => sprintf('Kontaktformular #%d', (int) $contact_form->id()),
            'message' => sanitize_textarea_field($data['your-message'] ?? ''),
        ]),
    ]);

    if (is_wp_error($response)) {
        return;
    }

    $result = json_decode(wp_remote_retrieve_body($response), true);

    if (($result['verdict'] ?? '') === 'blocked') {
        add_filter('wpcf7_skip_mail', '__return_true');
    }
});

WordPress: WPForms

Example for WPForms. Validate the fields before mail delivery and mark spam submissions as an error.

Insert in: wp-content/themes/YOUR-CHILD-THEME/functions.php (alternatively own plugin)



add_action('wpforms_process', function ($fields, $entry, $form_data, $entry_id) {
    $sender = '';
    $recipient = get_option('admin_email');
    $subject = $form_data['settings']['form_title'] ?? 'WPForms Anfrage';
    $message = '';

    foreach ($fields as $field) {
        if (! empty($field['type']) && $field['type'] === 'email') {
            $sender = sanitize_email($field['value'] ?? '');
        }

        $message .= is_array($field['value']) ? implode(' ', $field['value']) : (string) ($field['value'] ?? '');
        $message .= "\n";
    }

    $response = wp_remote_post('https://antispam.example.com/api/v1/scan', [
        'timeout' => 10,
        'headers' => [
            'Accept' => 'application/json',
            'Content-Type' => 'application/json',
            'X-Spam-Username' => 'dein-benutzername',
            'X-Spam-Password' => 'dein-passwort',
            'X-Spam-ApiKey' => 'dein-api-key',
        ],
        'body' => wp_json_encode([
            'sender' => $sender,
            'recipient' => $recipient,
            'subject' => $subject,
            'message' => trim($message),
        ]),
    ]);

    if (is_wp_error($response)) {
        return;
    }

    $result = json_decode(wp_remote_retrieve_body($response), true);

    if (($result['verdict'] ?? '') === 'blocked') {
        wpforms()->process->errors[$form_data['id']]['header'] = __('Das Formular wurde als Spam erkannt und nicht gesendet.', 'textdomain');
    }
}, 10, 4);

PrestaShop Guide

Recommended approach: create your own module and perform spam check before sending the contact request.

Create module file: modules/sentryform/sentryform.php
Intercept form data before mail sending (hook or controller override)
When verdict = blocked, stop sending and return an error message

class Sentryform extends Module
{
    public function install()
    {
        return parent::install();
    }

    private function checkSpam(array $payload): bool
    {
        // API aufrufen und true zurückgeben, wenn Spam erkannt wurde
        return false;
    }
}

Shopware 6 Guide

Recommended approach: create your own plugin under custom/plugins and extend contact form processing with spam check.

Create plugin structure: custom/plugins/SentryForm/src
Register service/subscriber and check on form submit
When verdict = blocked, set validation error and abort sending

class ContactSpamSubscriber implements EventSubscriberInterface
{
    public static function getSubscribedEvents(): array
    {
        return [
            // Kontaktformular-Event hier registrieren
        ];
    }

    public function onContactSubmit($event): void
    {
        // API aufrufen und bei Spam den Submit abbrechen
    }
}

If you have any questions or problems, please contact our support at support@sentryform.online