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

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 can be switched off for an account. While it is off, every endpoint returns 403 PUBLIC_API_DISABLED, whatever the request:

{
  "error": {
    "code": "PUBLIC_API_DISABLED",
    "message": "Public API access is disabled for this account. Contact support to restore 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 restored.

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 switched off 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.