Authorization

To use the API, you need to authenticate your requests using an API token.

Getting Your API Token

1. Go to https://cart.easy.tools/creator/email/settings/developer
2. Generate a new API token
3. Copy and securely store your token

A token on its own does not let you call the API — the account also needs API access enabled.

Using the API

Base URL

All API requests should be made to:

https://email.easy.tools/api/v1

Authentication

Include your API token in the Authorization header using Bearer authentication:

Authorization: Bearer YOUR_API_TOKEN

It's important to also include these headers in all requests:

Content-Type: application/json
Accept: application/json

Example Request

curl -H "Authorization: Bearer YOUR_API_TOKEN" \
     -H "Content-Type: application/json" \
     -H "Accept: application/json" \
     https://email.easy.tools/api/v1/contacts

API Access

API access is granted per account. It is off until it is enabled — a new account does not have it, and generating an API token does not grant it. Access can also be switched off later for an account that had it.

While access is off, every endpoint returns 403 PUBLIC_API_DISABLED, whatever the request:

{
  "error": {
    "code": "PUBLIC_API_DISABLED",
    "message": "Public API access is not enabled for this account. Contact support to enable it."
  }
}

This is not an authentication failure — a missing or invalid token returns 401 instead — and it is not a rate limit. Changing the request does not help; access stays off until the account owner contacts support to have it enabled.

Rate Limiting

The API enforces rate limiting per account:

• 100 requests per 60 seconds

Rate Limit Headers

All responses include rate limit information:

Header	Description
X-RateLimit-Limit	Maximum requests allowed in the window

When rate limited, additional headers are included:

Header	Description
X-RateLimit-Remaining	Requests remaining (always 0 when limited)
Retry-After	Seconds until the rate limit resets

Rate Limit Error (429 Too Many Requests)

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Too many requests. Please retry after 60 seconds."
  }
}

Response Formats

Success Response

All successful responses wrap data in a data key:

{
  "data": { ... }
}

Error Response

Almost all error responses follow this format (the exception is 401, described under Common Error Codes):

{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error message"
  }
}

Validation errors include additional details field with field-specific messages:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "The given data was invalid",
    "details": {
      "email": ["The email field is required."]
    }
  }
}

Date/Time Format

All timestamps use ISO 8601 format in UTC: YYYY-MM-DDTHH:mm:ssZ

Example: 2025-01-15T10:30:00Z

Common Error Codes

Status	Code	Description
401	—	Missing or invalid API token (plain message body — see note)
403	FORBIDDEN	The action is not permitted for this resource
403	PLAN_INACTIVE	Sending and creating contacts are not allowed for this account
403	PUBLIC_API_DISABLED	API access is not enabled for this account
404	RESOURCE_NOT_FOUND	Requested resource does not exist
409	DUPLICATE_RESOURCE	Resource already exists (e.g., duplicate email)
422	VALIDATION_ERROR	Invalid input data
429	RATE_LIMITED	Too many requests
500	SERVER_ERROR	Unexpected server error
503	SERVICE_UNAVAILABLE	The request could not be completed; retry it

Note on 401: Authentication failures return a plain { "message": "..." } body — for example "No API token provided" or "Invalid API token" — not the error envelope used by the other status codes.