Quickstart

1. Get your API key

Sign in to the Encrata dashboard and create a key from the API Keys page. Your key is shown once when it is created, so copy it and store it securely. Your key starts with enc_ and is tied to your account. Keep it server-side and never commit it to source control.

Already set up and want to manage keys from code? Use POST /api/account/keys to create and rotate keys programmatically.

2. Validate your first email

The fastest way to see the API work is the Email Validity endpoint. Send an address to POST /api/lookup/email/validity and Encrata tells you whether it is safe to send to - valid, invalid, catch-all, or risky - along with the reason, provider, and domain trust signals. It is the same check you would run to scrub a list before a campaign and cut bounces. Every request authenticates with your API key in the Authorization header:

Authorization: Bearer enc_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

curl -X POST "https://developer.encrata.com/api/lookup/email/validity" \
  -H "Authorization: Bearer enc_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"email": "satya@microsoft.com"}'

import requests

resp = requests.post(
    "https://developer.encrata.com/api/lookup/email/validity",
    headers={"Authorization": "Bearer enc_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"},
    json={"email": "satya@microsoft.com"},
)
print(resp.json())

const resp = await fetch("https://developer.encrata.com/api/lookup/email/validity", {
  method: "POST",
  headers: {
    Authorization: "Bearer enc_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ email: "satya@microsoft.com" }),
});
const data = await resp.json();
console.log(data);

package main

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

func main() {
	body, _ := json.Marshal(map[string]string{"email": "satya@microsoft.com"})
	req, _ := http.NewRequest("POST", "https://developer.encrata.com/api/lookup/email/validity", bytes.NewBuffer(body))
	req.Header.Set("Authorization", "Bearer enc_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx")
	req.Header.Set("Content-Type", "application/json")

	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()

	var result map[string]interface{}
	json.NewDecoder(resp.Body).Decode(&result)
	fmt.Println(result)
}

3. Read the response

A 200 OK returns the verdict plus enrichment. The two fields you will branch on are status (the public verdict) and reason (the machine-readable cause):

{
  "email": "satya@microsoft.com",
  "status": "valid",
  "reason": "deliverable",
  "disposable": false,
  "confidence": "high",
  "role": false,
  "role_name": "",
  "did_you_mean": "",
  "domain": "microsoft.com",
  "provider": "microsoft",
  "free_provider": false,
  "mx": ["microsoft-com.mail.protection.outlook.com"],
  "domain_trust": {
    "grade": "A",
    "spf": true,
    "dmarc": true,
    "mta_sts": "enforce",
    "spf_record": "v=spf1 include:_spf.example.com -all",
    "dmarc_record": "v=DMARC1; p=reject"
  },
  "domain_info": {
    "registrar": "Example Registrar",
    "created_at": "1995-08-14T00:00:00Z",
    "expires_at": "2027-08-13T00:00:00Z",
    "age_days": 11377,
    "nameservers": ["ns1.example.com"],
    "dnssec": true,
    "a": ["192.0.2.10"]
  },
  "smtp": {
    "mx_host": "mx.example.com",
    "message": "Mailbox accepted",
    "catch_all": false,
    "greylisted": false
  },
  "message": "Mailbox exists and accepts mail, safe to send.",
  "credits": 1,
  "cached": false
}

Each validation costs 1 credit. Repeat checks of the same address within the 6-month free-repeat window are free (credits: 0). See the full field reference on the Email Validity page.

Next steps

You made your first lookup. Here is where to go next.

Email Identity: Resolve an email into a full person profile.
All endpoints: Browse every lookup with request and response schemas.
Bulk operations: Look up thousands of emails in a single job.
Webhooks: Get notified when your bulk runs finish.

Overview

Configuration

Best practices

1. Get your API key

2. Validate your first email

3. Read the response

Next steps

​1. Get your API key

​2. Validate your first email

​3. Read the response

​Next steps

1. Get your API key

2. Validate your first email

3. Read the response

Next steps