Credit System

How credits work and pricing details

Smart Credit System

GTMAPIs uses a smart credit system that only charges for high-value personal emails. Role-based, catch-all, invalid, risky, and unknown results are free. New users receive a one-time 10,000-credit signup grant.

How Credits Work

1 Credit

Valid personal email

High B2B outbound value

0 Credits

Everything else

Role-based, catch-all, invalid, risky, unknown

What Gets Charged?

Charged (1 Credit) ✅

Only emails that meet ALL these criteria:

• ✅ Passes syntax validation
• ✅ Domain has MX records
• ✅ Mailbox verified via SMTP
• ✅ NOT role-based (info@, support@, etc.)
• ✅ NOT catch-all domain
• ✅ Has b2b_outbound_quality: "high"

Examples:

// [e-mail] - Personal email
{
  "result": "valid",
  "b2b_outbound_quality": "high",
  "credits_charged": 1
}

// [e-mail] - Personal email
{
  "result": "valid",
  "b2b_outbound_quality": "high",
  "credits_charged": 1
}

Free (0 Credits) 🆓

Everything else is completely FREE:

Role-Based Emails

// [e-mail]
{
  "result": "valid_role_based",
  "b2b_outbound_quality": "low",
  "credits_charged": 0,
  "charge_reason": "Role-based email - free for low B2B value"
}

Catch-All Domains

// [e-mail]
{
  "result": "risky",
  "b2b_outbound_quality": "none",
  "credits_charged": 0,
  "charge_reason": "Catch-all domain - cannot verify individual mailbox"
}

Invalid Emails

// [e-mail]
{
  "result": "invalid",
  "b2b_outbound_quality": "none",
  "credits_charged": 0,
  "charge_reason": "Domain has no MX records"
}

Unknown Verification

// [e-mail]
{
  "result": "unknown",
  "b2b_outbound_quality": "unknown",
  "credits_charged": 0,
  "charge_reason": "SMTP verification not permitted by server"
}

Why SMTP Uncertainty Is Free

SMTP verification can be blocked or made ambiguous by greylisting, temporary 4xx responses, provider policy blocks, connection timeouts, inconclusive 5xx responses, catch-all acceptance, or cloud/provider connection restrictions. GTMAPIs treats those outcomes conservatively:

• unknown means the mailbox was not proven valid or invalid because SMTP was temporary, blocked, timed out, or inconclusive.
• risky means catch-all behavior was detected, so the domain accepts addresses too broadly to prove the specific mailbox exists.
• Neither outcome is a High-Value Validation, so neither consumes credits.

This protects you from paying for ambiguous results. See Result Categories for response semantics, Validation Pipeline for where SMTP and catch-all checks fit in the flow, and Catch-all detection vs recovery for how opt-in recovery differs from standard validation.

Real-World Example

Uploaded CSV: 1,000 emails

Category	Count	Credits charged
Personal emails (high quality)	350	350
Role-based (info@, support@)	250	0
Catch-all domains	200	0
Invalid emails	150	0
Unknown/unverifiable	50	0
Total	1,000	350

You only spend credits on the 350 high-value validations, not on the full uploaded row count.

API and async job summaries expose this math directly:

{
  "high_value": 350,
  "catch_all": 200,
  "credits_reserved": 1000,
  "credits_consumed": 350,
  "credits_refunded": 650,
  "credits_per_high_value_validation": 1
}

Use credits_per_high_value_validation for cost per usable lead. Raw lookup count can hide the difference between high-value personal emails and role-based, catch-all, invalid, risky, or unknown outcomes that do not consume credits.

Credit Balance Tracking

Your dashboard shows:

{
  "balance": 9650,           // Current available credits
  "total_purchased": 10000,  // All-time purchased
  "total_consumed": 350      // All-time consumed
}

Signup Credits and Paid Plans

Signup Credits are a one-time 10,000-credit grant for new users. Paid plans add monthly credits from the canonical billing plan catalog:

Plan	Monthly credits	Price	Approx. price per credit
Starter	25,000	$99/mo	$0.004
Growth	75,000	$199/mo	$0.003
Pro	200,000	$399/mo	$0.002

One credit equals one High-Value Validation. Role-based, catch-all, invalid, risky, and unknown results cost 0 credits.

Credit Deduction Flow

Reservation and Finalization Timing

Single-email validation reserves one credit before provider work, then refunds it if the result is not high-value.

CSV and batch validation reserve enough credits for the unique emails being processed, then refund unused credits when final results are known:

1. ✅ Upload CSV
2. ✅ Reserve credits for unique emails
3. ✅ Perform validation
4. ✅ Count high-quality emails
5. ✅ Finalize charged credits and refund the rest
6. ✅ Return results

The reservation prevents jobs from starting without enough balance. Your final charge still only reflects high-value validations.

Insufficient Credits

If you don’t have enough credits to reserve the request:

{
  "error": "Insufficient credits",
  "required": 1000,
  "available": 500,
  "shortage": 500,
  "message": "You need 500 more credits to process this request"
}

Solutions:

• Reduce batch size
• Purchase more credits
• Process in multiple batches

API Key Prefixes

Prefix	Use
gtm_test_*	Development and test integrations
gtm_live_*	Production integrations

Test and live prefixes identify intended usage, but both must be valid account keys and both follow the normal access, rate-limit, and credit policy unless product docs state otherwise.

Credit Audit Trail

Every validation is tracked in credit_transactions:

{
  "id": "txn_123",
  "user_id": "user_456",
  "amount": -350,           // Negative = deduction
  "balance_after": 9650,
  "transaction_type": "validation",
  "metadata": {
    "validation_id": "val_789",
    "emails_processed": 1000,
    "emails_charged": 350,
    "email_types": {
      "high_quality": 350,
      "role_based": 250,
      "catch_all": 200,
      "invalid": 150,
      "unknown": 50
    }
  },
  "created_at": "2025-01-02T10:30:00Z"
}

Free Provider Emails

Question: Do you charge for Gmail/Yahoo/Outlook emails?

Answer: Yes, if they’re personal and valid.

// [e-mail] - Still charged
{
  "email": "[e-mail]",
  "result": "valid",
  "is_free_provider": true,
  "is_role_based": false,
  "b2b_outbound_quality": "high",
  "credits_charged": 1,
  "charge_reason": "Valid personal email with high B2B outbound quality"
}

Why? Many freelancers and small business owners use personal emails for business. They’re still valuable for B2B outreach.

API Response Fields

Every validation includes credit information:

interface ValidationResult {
  // ... other fields
  credits_charged: 0 | 1;
  charge_reason: string;
  b2b_outbound_quality: 'high' | 'low' | 'none' | 'unknown';
}

Best Practices

Optimize Credit Usage

1. Deduplicate first - Remove duplicates before uploading
2. Filter obvious invalids - Basic syntax checks locally
3. Batch processing - Upload all at once for efficiency
4. Use separate test keys - Develop with a dedicated test key before switching production systems to a live key

Monitor Credit Usage

1. Check dashboard regularly - Track balance and consumption
2. Set up alerts - Get notified at low balance
3. Review transactions - Audit credit deductions
4. Analyze quality distribution - Understand your list quality

Maximize ROI

1. Focus on high-quality - Prioritize charged emails in campaigns
2. Track conversion rates - Measure ROI per quality tier
3. Improve list sources - Buy from quality sources
4. Clean regularly - Keep lists fresh

Next Steps

B2B Quality Scoring

Learn what makes an email high-quality

Catch-all Detection vs Recovery

Understand why standard catch-all outcomes are free.

API Reference

Start validating emails