Kotlin - SpamBlock API and Forms Integration

Learn how to integrate SpamBlock API and Forms solution with Kotlin Android apps using Retrofit. Complete example with spam checking before form submission.

Overview

This example shows how to integrate both the SpamBlock API and SpamBlock Forms solution with Kotlin Android applications using Retrofit. Note: The SpamBlock Pixel is web-only and cannot run in Android apps. However, you can use the SpamBlock API directly to check submissions for spam, and submit to SpamBlock Forms endpoints.

Note: While you can use any backend endpoint, this example specifically demonstrates using both the SpamBlock API and SpamBlock Forms together. The SpamBlock Forms endpoint (https://api.spamblock.io/f/{form_id}) provides a complete hosted form solution. Learn more about Forms or use your own backend endpoint.

Step 1: Add Retrofit Dependencies

Add to your build.gradle.kts:

dependencies {
    implementation("com.squareup.retrofit2:retrofit:2.9.0")
    implementation("com.squareup.retrofit2:converter-gson:2.9.0")
}

Step 2: Create API Interface

import retrofit2.http.Body
import retrofit2.http.POST

interface SpamBlockApi {
    @POST("v1/check")
    suspend fun checkSpam(@Body request: SpamCheckRequest): SpamCheckResponse
    
    @POST("forms/{form_id}")
    suspend fun submitForm(@Body request: FormSubmissionRequest): FormSubmissionResponse
}

Step 3: Create Data Classes

data class SpamCheckRequest(
    val email: String,
    val message: String,
    val name: String
)

data class SpamCheckResponse(
    val allowed: Boolean,
    val score: Int
)

data class FormSubmissionRequest(
    val email: String,
    val message: String,
    val name: String
)

data class FormSubmissionResponse(
    val success: Boolean
)

Step 4: Implement Form Submission

import android.os.Bundle
import android.widget.Toast
import androidx.appcompat.app.AppCompatActivity
import kotlinx.coroutines.CoroutineScope
import kotlinx.coroutines.Dispatchers
import kotlinx.coroutines.launch
import retrofit2.Retrofit
import retrofit2.converter.gson.GsonConverterFactory

class ContactFormActivity : AppCompatActivity() {
    private lateinit var api: SpamBlockApi
    
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_contact_form)
        
        val retrofit = Retrofit.Builder()
            .baseUrl("https://api.spamblock.io/")
            .addConverterFactory(GsonConverterFactory.create())
            .build()
        
        api = retrofit.create(SpamBlockApi::class.java)
    }
    
    private fun submitForm(name: String, email: String, message: String) {
        CoroutineScope(Dispatchers.IO).launch {
            try {
                // First, check for spam
                val spamRequest = SpamCheckRequest(
                    email = email,
                    message = message,
                    name = name
                )
                
                val spamResponse = api.checkSpam(spamRequest)
                
                if (spamResponse.allowed) {
                    // If allowed, submit the form
                    val formRequest = FormSubmissionRequest(
                        name = name,
                        email = email,
                        message = message
                    )
                    
                    val formResponse = api.submitForm(formRequest)
                    
                    if (formResponse.success) {
                        runOnUiThread {
                            Toast.makeText(
                                this@ContactFormActivity,
                                "Submission successful!",
                                Toast.LENGTH_SHORT
                            ).show()
                        }
                    }
                } else {
                    // Blocked as spam
                    runOnUiThread {
                        Toast.makeText(
                            this@ContactFormActivity,
                            "Submission blocked as spam",
                            Toast.LENGTH_SHORT
                        ).show()
                    }
                }
            } catch (e: Exception) {
                runOnUiThread {
                    Toast.makeText(
                        this@ContactFormActivity,
                        "Error: ${e.message}",
                        Toast.LENGTH_SHORT
                    ).show()
                }
            }
        }
    }
}

What This Example Shows

  • How to integrate SpamBlock API with Kotlin Android apps
  • Using Retrofit with Kotlin coroutines
  • Spam checking before form submission
  • Suspend functions for async operations

When to Use It

Use this approach when:

  • You're building a Kotlin Android application
  • You're using Retrofit for API calls
  • You prefer Kotlin coroutines over callbacks
  • You need spam protection in native apps

How it Works

  1. User fills out form in Android app
  2. User submits form
  3. App calls SpamBlock API to check submission
  4. If spam: submission blocked, user notified
  5. If allowed: submission sent to your backend
  6. Success/error feedback shown to user

Important Notes

  • Pixel is web-only: The SpamBlock Pixel cannot run in Android apps
  • API integration: Use the SpamBlock API directly (/v1/check endpoint)
  • Coroutines: Requires Kotlin coroutines dependency
  • Network permissions: Add internet permission to AndroidManifest.xml
  • API key: You may need an API key for production use

Common Mistakes

  1. Trying to use Pixel - Pixel is JavaScript and won't work in Android
  2. Missing coroutines - Add implementation("org.jetbrains.kotlinx:kotlinx-coroutines-android:1.6.4")
  3. Missing network permission - Add internet permission to AndroidManifest.xml
  4. Not checking spam first - Always check with SpamBlock API before submitting
  5. UI thread operations - Use runOnUiThread for UI updates from background threads
  6. Exception handling - Always wrap API calls in try/catch

Learn More