CSV Upload Guide

Upload and validate CSV files through the dashboard or signed-upload API flow

CSV Upload Guide

Upload and validate CSV files through the GTMAPIs dashboard or the public signed-upload API flow. Dashboard uploads are designed for interactive CSV jobs; API integrations that need larger files should use the signed-upload flow in Async Validation Jobs.

Prerequisites

Before uploading a CSV:

• Create an account
• Generate an API key
• Ensure you have sufficient credits

Step-by-Step Process

1. Prepare Your CSV

   Your CSV must contain an email column. Other columns are preserved in the output.

2. Upload to Dashboard

   Go to Dashboard and click “Upload CSV”

3. Map Email Column

   Select which column contains email addresses

4. Start Validation

   Click “Validate” to begin processing

5. Receive Results

   Download CSV with validation results or receive via email

CSV Format Requirements

Supported Formats

• File type: .csv only
• Dashboard max size: 10,000 emails per upload
• API large-file flow: use signed upload preparation and start-processing endpoints
• Encoding: UTF-8 recommended
• Delimiter: Comma (,)

Example Input CSV

email,first_name,last_name,company
[e-mail],John,Doe,Acme Inc
[e-mail],Info,Team,Acme Inc
[e-mail],Invalid,User,Fake Corp
[e-mail],Sarah,Williams,Startup LLC

Column Mapping

During upload, you’ll select which column contains emails:

• Preview shows first 5 rows
• Click on the column header to select
• System validates format before processing

Output Format

Added Validation Columns

Your output CSV includes 11 new columns with validation results. These are the CSV Result Adapter field names; email_status, credits_consumed, is_domain_catch_all, and b2b_quality are compatibility aliases for the canonical validation result contract.

Column	Description	Example Values
email_status	Validation result	valid, valid_role_based, risky, invalid, unknown
credits_consumed	Credits used	0, 1
syntax_valid	Syntax validation flag	true, false
dns_valid	DNS/MX validation flag	true, false
smtp_valid	SMTP validation flag	true, false
is_domain_catch_all	Catch-all flag	true, false
is_role_based	Role-based flag	true, false
mx_record	Primary MX record	aspmx.l.google.com
mx_provider	Email provider	Google Workspace, Microsoft 365
b2b_quality	B2B quality score	high, low, none, unknown
domain	Email domain	company.com

Example Output CSV

email,first_name,last_name,company,email_status,credits_consumed,syntax_valid,dns_valid,smtp_valid,is_domain_catch_all,is_role_based,mx_record,mx_provider,b2b_quality,domain
[e-mail],John,Doe,Acme Inc,valid,1,true,true,true,false,false,aspmx.l.google.com,Google Workspace,high,company.com
[e-mail],Info,Team,Acme Inc,valid_role_based,0,true,true,true,false,true,aspmx.l.google.com,Google Workspace,low,company.com
[e-mail],Invalid,User,Fake Corp,invalid,0,true,false,false,false,false,,,none,notreal.com
[e-mail],Sarah,Williams,Startup LLC,valid,1,true,true,true,false,false,mx.startup.io,,high,startup.io

Processing Details

Batch Processing

The system processes emails in batches:

1. Deduplication: Removes duplicate emails (case-insensitive)
2. Batch size: 100 emails per API request
3. Delay: 500ms between batches to avoid rate limits
4. Retry logic: Automatic retry on transient failures

Processing Time

Processing time varies based on DNS caching, SMTP responsiveness, provider budgets, and job size. Use the dashboard or job status endpoint to monitor progress instead of assuming fixed completion times.

Email Notification

When validation completes:

• Email sent to your account address
• CSV file attached
• Summary statistics included

Credit Usage

How Credits Are Reserved and Finalized

CSV jobs reserve credits before validation starts, then finalize the charge after results are known:

1. Upload CSV
2. System reserves credits for unique emails
3. System validates all emails
4. Counts high-quality results
5. Charges only for result: "valid" + b2b_outbound_quality: "high"
6. Refunds the unused reserved credits
7. Returns results

Example Credit Usage

Uploaded CSV: 1,000 emails

Result	Count	Credits
Valid personal	400	400
Role-based	250	0 (FREE)
Catch-all	200	0 (FREE)
Invalid	100	0 (FREE)
Unknown	50	0 (FREE)
Total	1,000	400

The job may reserve up to the unique email count before processing, but the final charge is 400 credits.

Insufficient Credits

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

• Upload is rejected before processing starts
• Error message shows required vs available
• No partial processing (all-or-nothing)

Solution: Purchase more credits or reduce batch size

Best Practices

Before Uploading

Clean Your Data

Remove obvious invalids and duplicates locally:

// Remove duplicates
const unique = [...new Set(emails.map(e => e.toLowerCase()))];

// Basic syntax filter
const validFormat = unique.filter(e => /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(e));

// Remove common placeholders
const cleaned = validFormat.filter(e =>
  !e.includes('example.com') &&
  !e.includes('test@') &&
  !e.includes('@test.')
);

Verify CSV Format

Check your CSV before uploading:

• Proper comma delimiters
• No missing headers
• Consistent column count per row
• UTF-8 encoding (especially for international names)
• No BOM (Byte Order Mark) issues

Test With Small Sample

Before processing 10,000 emails:

1. Extract first 100 rows
2. Upload test batch
3. Review results quality
4. Adjust source or filters if needed
5. Process full list

After Validation

Filter by Quality

Separate emails by B2B quality:

// High quality for primary campaigns
const highQuality = results.filter(r =>
  r.result === 'valid' && r.b2b_outbound_quality === 'high'
);

// Role-based for secondary outreach
const roleBased = results.filter(r =>
  r.result === 'valid_role_based'
);

// Remove these completely
const toRemove = results.filter(r =>
  r.result === 'invalid' || r.result === 'risky'
);

Track Validation History

Keep records of validations:

• Original upload date
• Source of emails
• Validation results summary
• Credits consumed
• Campaign performance per quality tier

Re-validate lists every 3-6 months as emails change

Measure ROI

Compare campaign performance by quality:

High Quality Emails:
- Personal mailbox ownership
- Credits charged: 1 per result

Role-Based Emails:
- Shared inbox behavior
- Credits charged: 0 per result

Risky/Invalid/Unknown:
- Avoid or test carefully depending on status
- Credits charged: 0 per result

Common Issues

CSV Upload Fails

Problem: “Invalid CSV format” error

Causes:

• Non-UTF-8 encoding
• Inconsistent column counts
• Missing headers
• Special characters in data

Solution:

1. Open CSV in text editor
2. Check for encoding issues
3. Verify all rows have same column count
4. Remove special characters or escape properly

No Email Column Detected

Problem: System can’t find email column

Causes:

• Column named something other than “email”
• Emails in wrong format
• Empty column

Solution:

1. Rename column to “email” (lowercase)
2. Verify emails are in [e-mail] format
3. Check first few rows have valid data

Processing Takes Too Long

Problem: Validation stuck or timing out

Causes:

• Large batch size
• Many slow SMTP servers
• Network issues

Solution:

1. Check processing status in dashboard
2. Wait for email notification
3. If > 30 minutes, contact support
4. Try smaller batches (< 5,000 emails)

Unexpected Credit Charges

Problem: Charged more credits than expected

Causes:

• Misunderstanding of credit system
• More high-quality emails than estimated
• Duplicates not removed

Solution:

1. Check CSV for duplicate emails
2. Review validation results
3. Filter by credits_charged column
4. Only valid + b2b_outbound_quality: "high" are charged

Programmatic CSV Validation

For automation, use the API directly:

const fs = require('fs');
const Papa = require('papaparse');

async function validateCSV(filePath) {
  // 1. Read CSV
  const csvData = fs.readFileSync(filePath, 'utf8');
  const parsed = Papa.parse(csvData, { header: true });

  // 2. Extract emails
  const emails = parsed.data.map(row => row.email).filter(Boolean);

  // 3. Validate in batches
  const results = [];
  for (let i = 0; i < emails.length; i += 100) {
    const batch = emails.slice(i, i + 100);

    const response = await fetch('https://api.gtmapis.com/v1/validate/bulk', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'X-API-Key': process.env.GTMAPIS_API_KEY
      },
      body: JSON.stringify({ emails: batch })
    });

    const batchResults = await response.json();
    results.push(...batchResults.results);

    // Rate limit delay
    await new Promise(resolve => setTimeout(resolve, 500));
  }

  // 4. Merge results with original data
  const merged = parsed.data.map(row => {
    const result = results.find(r => r.email === row.email);
    return { ...row, ...result };
  });

  // 5. Write output CSV
  const csv = Papa.unparse(merged);
  fs.writeFileSync('output.csv', csv);

  console.log(`Validated ${results.length} emails`);
  return merged;
}

Next Steps

Upload CSV Now

Start validating your email list

API Integration

Integrate validation into your app