API Instructions

If you run a Eonvelope server or have access to one, the easiest way to get started with the API is via the redoc and swagger interfaces.

These can be found under /api/schema/redoc and /api/schema/swagger. The redoc interface for the user management API can be found under /api/auth/openapi.html.

Alternatively you can also get a raw yaml OpenAPI schema from /api/schema. The raw user management API schema is available under /api/auth/openapi.yaml or /api/auth/openapi.json.

Note

These interfaces are not available in slim mode.

If you have no option to run Eonvelope, you can refer to the API-schema section for the same schema files. You can render it to any API overview using one of the existing webtools or the docker image provided by swagger

docker run -p 8080:8080 -e SWAGGER_JSON=/schema.yml -v /path/to/schema.yml:/schema.yml swaggerapi/swagger-ui

In general the URLs of the API endpoints are designed in parallel to the webapps URLs with a prefix /api/v1/.

Note

All endpoints for interactions with the data and for authentication via api do not end in a slash.

To get an idea of what the different endpoints do try using the webapp or reading its manual first.

In addition to the features of the webapp the API offers vastly extended options for filtering. It also always you to download hand-picked email, attachment and correspondent files in batches as compact mailbox formats.

Note

If you dont proxy Eonvelope and want to request the API, you will have to ignore the self-signed certificate warnings. Using cURL you can do so via the -k option.

API Schema

The API version of the django-allauth user management is not documented in this schema. Please refer to its own OpenAPI schema for full information. Replace _allauth in their URLs with api/auth to map it to the Eonvelope endpoints.

Authentication

To authenticate via the API you have 4 options:

  • Basic auth: Authenticate directly at every endpoint with your credentials.

    This option is only available if you don’t have multi-factor-authentication turned on.

    curl -kX 'GET' -u user:password https://eonvelope.mydomain.tld/api/v1/emails/1
  • Token authentication: Authenticate via an API token.

    You can get a persistent one from the admin panel. This method is recommended for use in scripts and manual use.

    curl -kX 'GET' -H 'Authorization: Token your_key' https://eonvelope.mydomain.tld/api/v1/emails/1
  • Session authentication: Authenticate using a session cookie.

    This always requires that you add a recent CSRF token to the request. You can find one in the cookies of the web-interface.

    curl -kX 'GET' -b 'sessionid=your_session_cookie; csrftoken=your_csrf_token' -H 'X-CSRFTOKEN: your_csrf_token' https://eonvelope.mydomain.tld/api/v1/emails/1
  • Session Token Authentication: Authenticate using a session token.

    This option is implemented by the API of headless django-allauth and is mostly intended for use by alternative frontends.

    curl -kX 'POST' -d '{"username": "myname", "password": "mypwd"}' https://eonvelope.mydomain.tld/api/auth/app/v1/auth/login

    This will return a session token in the meta section of the json response. Note the missing / at the end of the login URL.

    curl -kX 'GET' -H 'X-Session-Token: your_token' https://eonvelope.mydomain.tld/api/v1/emails/1

For more details see the django restframework documentation on the matter.

Gotcha Notes

There may be a few unexpected quirks in the api, especially when it comes to field naming. These are listed here.

Version 1

The mail_address field returned by account endpoints refers to the username field from the web interface. It does NOT need to contain a valid mail_address. The outward facing name in the web interface was changed to ‘username’ for semantic compatibility with JMAP.