Authorization

To use the easymail 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

Rate Limiting

The API enforces rate limiting per tenant:

• 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

All error responses follow this format:

{
  "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	UNAUTHORIZED	Missing or invalid API token
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