> ## Documentation Index > Fetch the complete documentation index at: https://gtmapis.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # 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 **Valid personal email** High B2B outbound value **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**: ```json theme={null} // john@company.com - Personal email { "result": "valid", "b2b_outbound_quality": "high", "credits_charged": 1 } // sarah.williams@startup.io - Personal email { "result": "valid", "b2b_outbound_quality": "high", "credits_charged": 1 } ``` ### Free (0 Credits) 🆓 Everything else is completely **FREE**: #### Role-Based Emails ```json theme={null} // info@company.com { "result": "valid_role_based", "b2b_outbound_quality": "low", "credits_charged": 0, "charge_reason": "Role-based email - free for low B2B value" } ``` #### Catch-All Domains ```json theme={null} // anyone@catchall.com { "result": "risky", "b2b_outbound_quality": "none", "credits_charged": 0, "charge_reason": "Catch-all domain - cannot verify individual mailbox" } ``` #### Invalid Emails ```json theme={null} // notreal@fake123.com { "result": "invalid", "b2b_outbound_quality": "none", "credits_charged": 0, "charge_reason": "Domain has no MX records" } ``` #### Unknown Verification ```json theme={null} // blocked@restrictive.com { "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](/concepts/result-categories) for response semantics, [Validation Pipeline](/concepts/validation-pipeline) for where SMTP and catch-all checks fit in the flow, and [Catch-all detection vs recovery](/concepts/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: ```json theme={null} { "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: ```typescript theme={null} { "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 ```mermaid theme={null} sequenceDiagram participant User participant API participant Validation participant Database User->>API: Upload CSV (1000 unique emails) API->>Database: Reserve 1000 credits Database-->>API: Balance: 10,000 API->>Validation: Validate all emails Validation-->>API: Results (350 high-quality) API->>Database: Finalize 350 credits and refund 650 Database-->>API: New balance: 9,650 API-->>User: Results + updated balance ``` ### 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: ```json theme={null} { "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`: ```typescript theme={null} { "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. ```json theme={null} // john@gmail.com - Still charged { "email": "john@gmail.com", "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: ```typescript theme={null} 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 Learn what makes an email high-quality Understand why standard catch-all outcomes are free. Start validating emails