Back to Profile

Hamcut API Documentation

Integrate spam detection and email rewriting into your applications

Overview

The Hamcut API allows you to programmatically analyze emails for spam detection and rewrite them to improve deliverability. All API requests require authentication using an API key.

Getting Started

  1. Create an API key in your profile (paid plans only)
  2. Include the API key in the Authorization header of your requests
  3. Make requests to the API endpoints described below

Authentication

All API requests must include your API key in the Authorization header using the Bearer token format:

Authorization: Bearer hk_prod_your_api_key_here

⚠️ Security: Never expose your API keys in client-side code or public repositories. Always keep them secure on your server.

Base URL

https://hamcut.com/api/v1
POST

/analyze

Analyze an email for spam detection. Returns verdict, confidence score, and actionable suggestions.

Request Body

{
  "text": "Your email content here",
  "trackUsage": true  // Optional, default: true
}

Response

{
  "ok": true,
  "data": {
    "verdict": "HAM",
    "confidence": 0.92,
    "spamScore": 0.15,
    "hamScore": 0.85,
    "model": "hamcut-v1",
    "topTokens": [
      { "token": "example", "score": 0.05 }
    ],
    "suggestions": [
      "Consider rephrasing..."
    ]
  },
  "usage": {
    "creditsDeducted": 1,
    "creditsRemaining": 99,
    "tier": "pro"
  }
}

Example Request (cURL)

curl -X POST https://hamcut.com/api/v1/analyze \
  -H "Authorization: Bearer hk_prod_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Hi there! Check out our amazing offer..."
  }'

Example Request (JavaScript)

const response = await fetch('https://hamcut.com/api/v1/analyze', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer hk_prod_your_api_key',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    text: 'Hi there! Check out our amazing offer...'
  })
});

const data = await response.json();
console.log(data);

Example Request (Python)

import requests

response = requests.post(
    'https://hamcut.com/api/v1/analyze',
    headers={
        'Authorization': 'Bearer hk_prod_your_api_key',
        'Content-Type': 'application/json'
    },
    json={
        'text': 'Hi there! Check out our amazing offer...'
    }
)

data = response.json()
print(data)
POST

/rewrite

Automatically rewrite an email to improve deliverability by replacing spam-triggering words and improving readability.

Request Body

{
  "text": "Your email content here",
  "maxIterations": 3,  // Optional, default: 3
  "trackUsage": true   // Optional, default: true
}

Response

{
  "ok": true,
  "data": {
    "rewrittenText": "Improved email content...",
    "originalText": "Your email content here",
    "analysis": {
      "originalSpamScore": 0.65,
      "originalVerdict": "SPAM",
      "finalSpamScore": 0.18,
      "finalVerdict": "HAM",
      "isHam": true,
      "iterations": 2,
      "changes": [
        "\"free\" → \"complimentary\"",
        "\"click here\" → \"learn more\""
      ],
      "remainingIssues": null
    }
  },
  "usage": {
    "creditsDeducted": 1,
    "creditsRemaining": 98,
    "tier": "pro"
  }
}

Example Request (cURL)

curl -X POST https://hamcut.com/api/v1/rewrite \
  -H "Authorization: Bearer hk_prod_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Click here for a free trial! Act now!"
  }'

Example Request (JavaScript)

const response = await fetch('https://hamcut.com/api/v1/rewrite', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer hk_prod_your_api_key',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    text: 'Click here for a free trial! Act now!',
    maxIterations: 3
  })
});

const data = await response.json();
console.log(data.data.rewrittenText);

Example Request (Python)

import requests

response = requests.post(
    'https://hamcut.com/api/v1/rewrite',
    headers={
        'Authorization': 'Bearer hk_prod_your_api_key',
        'Content-Type': 'application/json'
    },
    json={
        'text': 'Click here for a free trial! Act now!',
        'maxIterations': 3
    }
)

data = response.json()
print(data['data']['rewrittenText'])

Error Codes

401 - Unauthorized

Missing or invalid API key

MISSING_API_KEY, INVALID_API_KEY, KEY_DISABLED, KEY_EXPIRED

402 - Payment Required

Insufficient credits

INSUFFICIENT_CREDITS

400 - Bad Request

Missing or invalid request parameters

MISSING_TEXT, INVALID_NAME

500 - Internal Server Error

Server error - please try again

INTERNAL_ERROR

Credits & Pricing

Credit Usage

Each API call (analyze or rewrite) costs 1 credit

Enterprise Plan

Enterprise users have unlimited API calls with no credit deduction

Free Tier

API access is not available on the free tier. Upgrade to a paid plan to use the API.

View pricing plans to purchase more credits or upgrade to Enterprise for unlimited access.

Integrations

Connect Hamcut to HubSpot, Zapier, Make, n8n, or any tool that can call an HTTP endpoint or receive a webhook.

Outbound Webhook (any platform)

Pass an optional webhook_url in your /analyze request. After scoring, Hamcut will POST the full result to that URL - useful for triggering workflows in Zapier, Make, n8n, or HubSpot.

curl -X POST https://hamcut.com/api/v1/analyze \
  -H "Authorization: Bearer hk_prod_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Your email body here",
    "webhook_url": "https://hooks.zapier.com/hooks/catch/..."
  }'
Verifying delivery: Every webhook POST includes an X-Hamcut-Signature header - an HMAC-SHA256 of the request body signed with your API key. Verify it on your server to confirm the payload came from Hamcut.
HubSpot

Custom Code Workflow Action

In HubSpot Workflows, add a Custom Code action (Node 18). Store your API key as a HubSpot secret named HAMCUT_API_KEY, then use this snippet:

// HubSpot Custom Code Action - Node.js 18
exports.main = async (event, callback) => {
  const emailBody = event.inputFields['email_body'];

  const res = await fetch('https://hamcut.com/api/v1/analyze', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.HAMCUT_API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ text: emailBody }),
  });

  const { data } = await res.json();

  callback({
    outputFields: {
      hamcut_verdict:    data.verdict,       // "HAM", "SPAM", or "BORDERLINE"
      hamcut_spam_score: data.spamScore,
      hamcut_confidence: data.confidence,
    }
  });
};

Use hamcut_verdict in an If/Then Branch to route contacts - e.g. only enrol in a sequence when verdict is HAM.

Zapier

Webhooks by Zapier + HTTP Action

Two options in Zapier:

  1. Trigger on result: Pass your Zapier catch-hook URL as webhook_url in your API call. Hamcut will POST the verdict to Zapier automatically.
  2. Call from a Zap: Use the Webhooks by Zapier → POST action. Set URL to https://hamcut.com/api/v1/analyze, add header Authorization: Bearer hk_prod_..., and pass the email body as text.
Make

HTTP Module

Add an HTTP → Make a request module to your scenario:

URL:    https://hamcut.com/api/v1/analyze
Method: POST
Headers:
  Authorization: Bearer hk_prod_your_api_key
  Content-Type:  application/json
Body (raw JSON):
  { "text": "{{email.body}}" }
n8n

HTTP Request Node

Add an HTTP Request node with these settings:

Method:  POST
URL:     https://hamcut.com/api/v1/analyze
Auth:    Header Auth
  Name:  Authorization
  Value: Bearer hk_prod_your_api_key
Body:    JSON
  { "text": "{{ $json.emailBody }}" }

Support

Need help with the API? We're here to assist you.

Email: support@hamcut.com

Documentation: Check our blog for guides and tutorials