> ## 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.

# Quickstart

> Get started with GTMAPIs in 5 minutes

## Setup Your Account

<Steps>
  <Step title="Sign Up">
    Create your account at [gtmapis.com](https://www.gtmapis.com/sign-up)
  </Step>

  <Step title="Get Your API Key">
    Navigate to **Dashboard → API Keys** and generate a test key

    API keys follow this format:

    * Test keys: `gtm_test_1234567890abcdef1234567890abcdef`
    * Live keys: `gtm_live_1234567890abcdef1234567890abcdef`

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

  <Step title="Make Your First Request">
    Validate your first email with a simple cURL request
  </Step>
</Steps>

## Validate a Single Email

<CodeGroup>
  ```bash CLI theme={null}
  export GTMAPIS_API_KEY=gtm_test_1234567890abcdef1234567890abcdef
  gtmapis validate john@company.com
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.gtmapis.com/v1/validate \
    -H "Content-Type: application/json" \
    -H "X-API-Key: gtm_test_1234567890abcdef1234567890abcdef" \
    -d '{"email":"john@company.com"}'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.gtmapis.com/v1/validate', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-API-Key': 'gtm_test_1234567890abcdef1234567890abcdef'
    },
    body: JSON.stringify({
      email: 'john@company.com'
    })
  });

  const result = await response.json();
  console.log(result);
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      'https://api.gtmapis.com/v1/validate',
      headers={
          'Content-Type': 'application/json',
          'X-API-Key': 'gtm_test_1234567890abcdef1234567890abcdef'
      },
      json={
          'email': 'john@company.com'
      }
  )

  result = response.json()
  print(result)
  ```

  ```go Go theme={null}
  package main

  import (
      "bytes"
      "encoding/json"
      "net/http"
  )

  func main() {
      body := map[string]string{"email": "john@company.com"}
      jsonBody, _ := json.Marshal(body)

      req, _ := http.NewRequest("POST", "https://api.gtmapis.com/v1/validate", bytes.NewBuffer(jsonBody))
      req.Header.Set("Content-Type", "application/json")
      req.Header.Set("X-API-Key", "gtm_test_1234567890abcdef1234567890abcdef")

      client := &http.Client{}
      resp, _ := client.Do(req)
      defer resp.Body.Close()
  }
  ```
</CodeGroup>

## Response Format

```json theme={null}
{
  "email": "john@company.com",
  "result": "valid",
  "reason": "",
  "syntax_valid": true,
  "dns_valid": true,
  "smtp_valid": true,
  "is_catchall": false,
  "is_role_based": false,
  "b2b_outbound_quality": "high",
  "b2b_quality": "high",
  "credits_charged": 1,
  "charge_reason": "Valid personal email with high B2B outbound quality"
}
```

<ResponseField name="result" type="string" required>
  Validation result: `valid`, `valid_role_based`, `risky`, `invalid`, or `unknown`
</ResponseField>

<ResponseField name="b2b_outbound_quality" type="string" required>
  B2B quality score: `high`, `low`, `none`, or `unknown`
</ResponseField>

<ResponseField name="credits_charged" type="integer" required>
  Number of credits charged (0 or 1). Only high-value personal emails are charged.
</ResponseField>

## Validate Multiple Emails

Process up to 100 emails in a single request:

```bash CLI theme={null}
gtmapis bulk --file leads.csv
```

```bash theme={null}
curl -X POST https://api.gtmapis.com/v1/validate/bulk \
  -H "Content-Type: application/json" \
  -H "X-API-Key: gtm_test_1234567890abcdef1234567890abcdef" \
  -d '{
    "emails": [
      "john@company.com",
      "info@company.com",
      "invalid@fakeemail123.com"
    ]
  }'
```

## Check Credit Balance

```bash theme={null}
gtmapis credits
gtmapis credits --json
```

The credit command calls `GET https://api.gtmapis.com/v1/credits` with the same `X-API-Key` authentication model.

## Understanding Credit Charges

Only pay for emails that matter:

| Result             | B2B Quality | Credits Charged | Example                                           |
| ------------------ | ----------- | --------------- | ------------------------------------------------- |
| `valid`            | `high`      | ✅ 1 credit      | [john@company.com](mailto:john@company.com)       |
| `valid_role_based` | `low`       | 🆓 FREE         | [info@company.com](mailto:info@company.com)       |
| `risky`            | `none`      | 🆓 FREE         | catch-all domains                                 |
| `invalid`          | `none`      | 🆓 FREE         | [invalid@notreal.com](mailto:invalid@notreal.com) |
| `unknown`          | `unknown`   | 🆓 FREE         | restrictive SMTP servers                          |

## Next Steps

<CardGroup cols={2}>
  <Card title="Validation Pipeline" icon="sitemap" href="/concepts/validation-pipeline">
    Learn how our 4-layer validation works
  </Card>

  <Card title="B2B Quality Scoring" icon="star" href="/concepts/b2b-quality-scoring">
    Understand how we score emails for outbound value
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference/overview">
    Complete API documentation
  </Card>

  <Card title="MCP and Agent Tools" icon="bot" href="/guides/mcp-agent-tools">
    Use GTMAPIs safely from coding agents and GTM workflow agents
  </Card>

  <Card title="CSV Upload Guide" icon="file-csv" href="/guides/csv-upload">
    Upload and validate CSV files
  </Card>
</CardGroup>