Create an API key and make your first request

The InboxRoads REST API lets you add contacts from your website, verify addresses from your own app, and check your balance. The base URL is https://inboxroads.com/api/v1.

Create an API key

1. Go to Settings and find the API keys card. Your email address must be confirmed.
2. Enter a Key name that says where it's used, such as "Website signup form".
3. Click Create key.
4. Copy the key right away. It's shown only once.

Keep the key secret. It has full access to your account's API. To stop a key working, click Revoke next to it. The list shows when each key was last used.

Authenticate your requests

Send these headers with every request:

Authorization: Bearer YOUR_KEY
Accept: application/json

The API allows up to 120 requests per minute per account.

1. Check your credit balance

curl https://inboxroads.com/api/v1/credits \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Accept: application/json"

The response includes balance and your 20 most recent recent_transactions.

2. Add or update a contact

curl -X POST https://inboxroads.com/api/v1/contacts \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "jane@example.com",
    "first_name": "Jane",
    "last_name": "Doe",
    "company": "Example Co",
    "country": "US",
    "custom_fields": {"plan": "pro"},
    "lists": ["LIST_ID"],
    "consent_source": "website-form"
  }'

• email is required. The other fields are optional: first_name, last_name, company, phone, country (two-letter code), custom_fields, lists and consent_source.
• lists takes list IDs. Get them from GET /api/v1/lists, or create a list with POST /api/v1/lists.
• A new contact returns 201. An existing email is updated and returns 200.
• Only use this for people who agreed to receive your email. Suppressed addresses are created as unsubscribed.

3. Verify email addresses

curl -X POST https://inboxroads.com/api/v1/verify \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"emails": ["jane@example.com", "info@example.org"], "name": "Signup check"}'

• Send up to 50,000 addresses in emails. name is optional.
• The response is 202 with a job id. Credits are reserved once duplicates and malformed addresses are removed, and the job runs in the background.
• Check progress with GET /api/v1/verify/{id}. When status is completed, the response includes results, with each address's status and sub_status. See verification results explained.

If your balance is too low, the API returns 402 with an "Insufficient credits" message.

Other endpoints

GET /lists, POST /lists, GET /contacts (filter with ?email= or ?list=), GET /contacts/{id}, DELETE /contacts/{id}, GET /campaigns, GET /campaigns/{id} and GET /domains.

Key takeaways

• Create keys under Settings → API keys. They're shown only once.
• Send Authorization: Bearer YOUR_KEY and Accept: application/json with every request.
• Verification via the API starts automatically. Poll the job until it's completed.