Introduction

Request Requirements

When making a request, the following requirements must be met.

Headers

The following headers are required. Failure to supply these headers may lead to the API behaving in unexpected ways.

Accept

An Accept header should be provided, with the value application/json.

Content-Type

A Content-Type header should be supplied with the value application/json.

Authentication

Authentication for the API is performed on a per-workspace basis by supplying a token with the API request.

Generating Tokens

To view your existing tokens, or to generate a new token, perform the following steps for each of your Workspaces:

  • Click on your user name in the top right corner
  • Select API Tokens from the menu.
  • You will see a list of any previously generated API tokens, including when they were generated and an option to delete them.
  • To add a new token, optionally provide a description for the token, and then click Add Token.

You will now be able to use the generated token to authenticate with the API for the current workspace.

Bearer Token

The preferred way to authenticate with the API during a request is to use the token as a Bearer token. This is performed by supplying an Authorization header with the request, where the value is Bearer {api_token}.

Example

Authorization: Bearer 9w2fN7d4F3Banyv7gihYOWJEH6MvtYyZ

API Token Parameter

Alternatively, you can authenticate by providing the token as a parameter when making the request. The token parameter should be keyed as api_token where the value is {api_token}.

GET Example

/api/v1/ping?api_token=9w2fN7d4F3Banyv7gihYOWJEH6MvtYyZ

POST Example

{
    "api_token": "9w2fN7d4F3Banyv7gihYOWJEH6MvtYyZ"
}

Throttling

By default, the API is configured to limit requests to 60 per minute. When this limit is exceeded a 429 Too Many Requests response will be returned.

The limit can be configured by editing the LARAVELMAIL_THROTTLE_MIDDLEWARE key in the.env file. The value needs to be in the format {number_of_requests},{every_X_minutes}.

For example, this would limit the API to 1000 requests every 5 minutes:

LARAVELMAIL_THROTTLE_MIDDLEWARE=1000,5

For more information on rate limiting see the official Laravel documentation here.

Testing the API

You can easily test your API by performing a GET request against the /ping endpoint:

GET /api/v1/ping

If your API is working correctly, then this will return a 200 response with the string ok in the body content. Note that this endpoint does not require any authentication.

Errors

Authentication Error

An authentication error can occur when no token is provided, or the token is invalid.

Response Fields

  • message: string

Sample Missing Token Response

{
    "message": "Unauthenticated."
}

Sample Invalid Token Response

{
    "message": "Unauthenticated."
}

Validation Errors

When data provided in a request is invalid or missing you will receive an error response explaining what is wrong with the request.

Response Fields

  • message: string
  • errors: object

Sample Response

{
    "message": "The given data was invalid.",
    "errors": {
        "email": [
            "The email field is required."
        ]
    }
}

Pagination

Paginated responses follow this format:

  • data: array<object>
    • id: int
    • name: string
    • created_at: datetime
    • updated_at: datetime
  • links: object
    • first: string
    • last: string
    • prev: string|null
    • next: string|null
  • meta: object
    • current_page: int
    • from: int
    • last_page: int
    • path: string
    • per_page: int
    • to: int
    • total: int