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`, `subject`, and `message` together with the 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.
subject Yes Request subject.
message Yes Message body or form content.
ip No Remote IP Address

Response data

The API returns the spam score, verdict, and matched keywords. If `verdict = blocked`, stop processing the form. This is a sample response.

{

"code": 0,
"verdict": "accepted",
"score": 0,
"threshold": 6,
"detected_charset": "Latin",
"charset_blocked": false,
"detected_language": "de",
"language_blocked": false,
"message_id": 107,
"note": "Message approved"
}

Explicación del código de respuesta ('code')

AVISO: Este código es interno y no tiene nada que ver con el código HTTP.

Código Descripción
0 Message accepted, no error
100 Mensaje bloqueado
101 Dirección IP está en lista negra
102 Dirección de correo bloqueado
201 No clave API especificado
202 Clave API no válida
203 Tiempo de prueba expirado. Por favor obtenga plan superior
204 Dominio no autorizado para este clave API
205 Si se ha introducido alguno de ellos, es necesario introducir tanto el nombre de usuario como la contraseña.
206 Se ha introducido un nombre de usuario y/o una contraseña no válidos

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-ApiKey' => '[your-api-key]',
        'X-Spam-Referer' => '[your-domain]',
    ])
    ->post('https://api.sentryform.online/api/v1/scan', [
        'sender' => 'info@example.com',
        'subject' => 'Anfrage über das Kontaktformular',
        'message' => 'Hallo, ich interessiere mich für Ihr Angebot.',
        'ip' => '123.234.243.12'
    ]);

if ($response->json('verdict') === 'blocked') {
    // Spam detected: STOP processing form...
}

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://api.sentryform.online/api/v1/scan', {
  method: 'POST',
  headers: {
    'Accept': 'application/json',
    'Content-Type': 'application/json',
    'X-Spam-ApiKey': '[your-api-key]',
    'X-Spam-Referer': '[your-domain]',
  },
  body: JSON.stringify({
    sender: 'info@example.com',
    subject: 'Anfrage über das Kontaktformular',
    message: 'Hallo, ich interessiere mich für Ihr Angebot.',
    ip: '123.234.243.12'
  }),
});

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://api.sentryform.online/api/v1/scan" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "X-Spam-ApiKey: [your-api-key]" \
  -H "X-Spam-Referer: [your-domain]" \ 
  -d '{
    "sender": "info@example.com",
    "subject": "Anfrage über das Kontaktformular",
    "message": "Hallo, ich interessiere mich für Ihr Angebot.",
    "ip": "123.234.243.12"
  }'

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://api.sentryform.online/api/v1/scan', [
        'timeout' => 10,
        'headers' => [
            'Accept' => 'application/json',
            'Content-Type' => 'application/json',
            'X-Spam-ApiKey' => '[your-api-key]',
            'X-Spam-Referer' => parse_url(home_url(), PHP_URL_HOST)
        ],
        'body' => wp_json_encode([
            'sender' => sanitize_email($data['your-email'] ?? ''),
            'subject' => sprintf('Kontaktformular #%d', (int) $contact_form->id()),
            'message' => sanitize_textarea_field($data['your-message'] ?? ''),
            'ip' => $_SERVER['HTTP_X_REAL_IP'] ?? $_SERVER['REMOTE_ADDR']
        ]),
    ]);

    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) {
    $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://api.sentryform.online/api/v1/scan', [
        'timeout' => 10,
        'headers' => [
            'Accept' => 'application/json',
            'Content-Type' => 'application/json',
            'X-Spam-ApiKey' => '[your-api-key]',
            'X-Spam-Referer' => parse_url(home_url(), PHP_URL_HOST)
        ],
        'body' => wp_json_encode([
            'sender' => $sender,
            'subject' => $subject,
            'message' => trim($message),
            'ip' => $_SERVER['HTTP_X_REAL_IP'] ?? $_SERVER['REMOTE_ADDR']
        ]),
    ]);

    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, 3);

PrestaShop Guide

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

Show full guide

Shopware 6 Guide

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

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