---
title: "Using EmailGuard's API to Run Spam Filter Tests"
description: "Running spam filter tests through EmailGuard's API is straightforward once you get the hang of it."
url: https://help.emailguard.io/en/articles/23-using-emailguard-s-api-to-run-spam-filter-tests
collection: "Walkthroughs"
updated: 2026-10-19
language: en
---

# Using EmailGuard's API to Run Spam Filter Tests

Running spam filter tests through EmailGuard's API is straightforward once you get the hang of it.

## Before You Start: Get Your API Token

You'll need an API token to authenticate your requests. Here's how to grab one:

1.  Navigate to **Account Settings** in your EmailGuard dashboard
    
2.  Click on **Developer API**
    
3.  Create a new API token
    
4.  Copy it somewhere safe—you'll need it for the headers in your API requests
    

![](https://staticfiles.gleap.io/gattachments/bufW8SsAwMjZUWk6lXFZHMfdjLREwj2HdWOuV7z5mseF26vjS9WCwCFR6eJZHdBT8DCbd0umhbo.png)

## The Two-Step Process

### Step 1: Create the Spam Filter Test

First, you'll make a POST request to EmailGuard's spam filter test endpoint:

**Endpoint:** [https://app.emailguard.io/api/v1/spam-filter-tests](https://app.emailguard.io/api/reference#tag/spam-filter-tests/post/apiv1spam-filter-tests)

**Headers:**

```javascript
Authorization: Bearer [YOUR_API_TOKEN_HERE]
```

**Body:**

json

```json
{
  "name": EG API DEMO"
}
```

The `name` parameter is simply a label for this test, use something descriptive so you can identify it later.

When you make this request, EmailGuard will respond with the following:

```json
{
    "data": {
        "uuid": "a08a75e7-28c1-44db-a414-a28021c99e69",
        "name": "EG API DEMO",
        "status": "waiting_for_email",
        "spam_filter_email_address": "okdrghnn+a08a75e7-28c1-44db-a414-a28021c99e69@testseguard.com",
        "sent_from": null,
        "sending_server_ip": "Unknown",
        "score": null,
        "score_breakdown": null
    }
}
```

#### Understanding the Response

Here's what each field means:

-   **uuid** \- The unique identifier for this test. Keep this handy, you'll need it to fetch your results later
    
-   **name** \- The name you gave the test (in this case, "EG API DEMO")
    
-   **status** \- Shows where the test is at in the process. Right now it's waiting\_for\_email, meaning EmailGuard is ready for you to send your email
    
-   **spam\_filter\_email\_address** \- This is the key field, the email address you need to send your test email to
    
-   **sent\_from** \- Will populate with the email address you sent from once you send the email
    
-   **sending\_server\_ip** \- Will show the IP address your email was sent from
    
-   **score** \- Will contain your overall spam score after the email is analyzed (currently null since we haven't sent anything yet)
    
-   **score\_breakdown** \- Will contain detailed scoring information once the test completes
    

### Step 2: Send Your Email

Now comes the easy part, just send your actual email to the **spam\_filter\_email\_address** from the response above. This should be the same email you'd send to your prospects:

-   Include all your typical content
    
-   Send it exactly as you would in production
    

EmailGuard will run it through spam filters and analyze it for you.

![](https://staticfiles.gleap.io/gattachments/EpK9vs5wpGYnUntPRok11bJDARRK3WQ9EaTtwioYOZtw6M0bzMDiI4wi4kct6fezQigIxggAKYW.png)

Step 3: Fetch Your Results

Once EmailGuard processes your email (usually within a few seconds), you can fetch the results using the **uuid** from Step 1.

**Endpoint:** [**https://app.emailguard.io/api/v1/spam-filter-tests/{uuid}**](https://app.emailguard.io/api/reference#tag/spam-filter-tests/get/apiv1spam-filter-testsemail_test_uuid)

When you make the GET request, you'll receive a comprehensive breakdown of your email's performance:

```json
{
    "data": {
        "uuid": "a08a75e7-28c1-44db-a414-a28021c99e69",
        "name": "EG API DEMO",
        "status": "succeeded",
        "spam_filter_email_address": "okdrghnn+a08a75e7-28c1-44db-a414-a28021c99e69@testseguard.com",
        "sent_from": "your-email@domain.com",
        "sending_server_ip": "XXX.XXX.XXX.XX",
        "score": 3.89,
        "score_breakdown": {
            ...
        }
    }
}
```

### Understanding Your Score

The **score** field (3.89 in this example) is your overall spam score. Lower is better, you're aiming for scores close to 0 or negative.

The **score\_breakdown** contains dozens of individual checks that contribute to your final score. Here are some key ones to pay attention to:

**Infrastructure & Authentication:**

-   **MX\_GOOD (-0.01**) - Your domain has working MX records configured properly
    
-   **R\_SPF\_ALLOW** (-0.2) - SPF verification passed
    
-   **R\_DKIM\_ALLOW** (-0.2) - DKIM signature verified successfully
    
-   **DMARC\_POLICY\_ALLOW** (-0.5) - DMARC policy check passed
    

**Content & Format:**

-   **MIME\_GOOD** (-0.1) - Your email uses recognized, properly formatted content types
    

**Reputation Issues:**

-   **RBL\_SENDERSCORE** (+2.0) - Your sending IP is listed in senderscore.com's blocklist (this is adding to your spam score)
    
-   **BAD\_REP\_POLICIES** (+2.0) - Email contains valid authentication but is flagged by reputation systems
    

#### What Affects Your Score

Your final score is influenced by many factors beyond just the ones highlighted above. The complete **score\_breakdown** includes checks for:

-   **Your copy and subject line** - Spammy words, excessive capitalization, misleading subjects
    
-   **Your infrastructure setup** - IP reputation, domain authentication (SPF, DKIM, DMARC)
    
-   **Email format** - HTML structure, image-to-text ratio, broken links
    
-   **Sending behavior** - Recipient count, sending patterns, list quality
    
-   **Reputation databases** - Whether your IP or domain appears on any blocklists
    

Each email you test will have a unique combination of these factors, which is why it's important to test your actual production emails rather than generic samples.

  
Why Use the API?

Running tests via API is particularly useful when you:

-   Want to automate testing as part of your campaign workflow
    
-   Need to test multiple variations quickly
    
-   Want to integrate spam testing into your own tools or scripts
    
-   Need programmatic access to detailed scoring data
    

The API gives you the same robust testing EmailGuard offers in the dashboard, but with the flexibility to build it into your existing processes.

* * *

That's it! Two simple API calls and you've got comprehensive spam filter analysis without leaving your workflow.