Documentation de l'API

Our API is based on REST, it uses the    HTTP-related convenience, including verbs (GET, POST, PUT, DELETE, ...) and response codes.

Oui API endpoint is: https://protecmail.com/api/v1

Feel free to contact us if you would like to see other features implemented.

Authentification

Each request must be authenticated by the header Api-Key which must contain one of the keys created in your Customer Area: API key management

example curl :
$ curl https://protecmail.com/api/v1/ping --header "Api-Key: cdd4fc0a-2b4f-4336-90f8-77c72be60791"

{"request_id":"96989778-db33-4e1d-93ac-b2245a393097","success":true,"msg":"pong"}

Response

We respond to every request by:

  • an HTTP status code.
  • a JSON object Response

JSON Response object has the following structure:

  • request_id: unique identifier of the request.
  • success: boolean indicating whether the query has been successfully completed.
  • msg: an additional message if necessary.
  • data: additional data if necessary.
example:
$curl -vvv https://protecmail.com/api/v1/domain/example.tld/addresses --header "Api-Key: cdd4fc0a-2b4f-4336-90f8-77c72be60791"

< HTTP/1.1 200 OK
{"request_id":"7372ded9-bd12-40bf-ac9e-caf8fbb91d50","success":true,"data":["postmaster","john"]}

Account info

GET https://protecmail.com/api/v1/user

The JSON User object corresponding to the data property of the response has the following structure:

  • nic: Protecmail nic.
  • first_name: firstname.
  • last_name: lastname.
  • email: email address.
  • organisation: company.
  • tva_intra: VAT number.
  • address: address.
  • city: city.
  • country: country.
  • phone: phone.
example:
$ curl -vvv https://protecmail.com/api/v1/user --header "Api-Key: cdd4fc0a-2b4f-4336-90f8-77c72be60791"

< HTTP/1.1 200 OK
{"request_id":"af07b9b1-25c5-4690-ac1e-4240e5e66e26","success":true,"data":{"nic":"XX-42","first_name":"John","last_name":"Doe","email":"john@doe.com","organisation":"jd unlimited","tva_intra":"FR454545","address":"69 avenue de le pie","city":"Paris","zip":"75010","country":"FR","phone":"+3365478945"}}

Edit account

PUT https://protecmail.com/api/v1/user

The body of the request must contain the edited User object.

Example:
$ curl https://protecmail.com/api/v1/user --header "Api-Key: cdd4fc0a-2b4f-4336-90f8-77c72be60791" --header "Content-Type: application/json" --request PUT --data '{"first_name":"John","last_name":"Doe","email":"john@doe.com","organisation":"jd unlimited","tva_intra":"FR454545","address":"69 avenue de le pie qui chante","city":"Paris","zip":"75010","country":"FR","phone":"+3365478945"}'

< HTTP/1.1 200 OK
{"request_id":"7671a1f7-a7c4-4e3c-8575-a3e5e211fb9b","success":true}

Liste des factures

GET https://protecmail.com/api/v1/invoices

The JSON object returned in the data property is an array of items {"date", "ref", "total"}

Example:
$ curl https://protecmail.com/api/v1/invoices --header "Api-Key: cdd4fc0a-2b4f-4336-90f8-77c72be60791"

< HTTP/1.1 200 OK
{"request_id":"15172f05-20fa-4dcd-acd7-7a59d7bf54be","success":true,"data":[{"ref":5,"date":"2018-10-16T17:04:41+02:00","total":60},{"ref":4,"date":"2018-10-16T15:25:08+02:00","total":720},{"ref":3,"date":"2018-10-15T16:08:04+02:00","total":720},{"ref":1,"date":"2018-10-30T14:36:52.897435613+01:00","total":724.8}]}

Télécharger une facture

GET https://protecmail.com/api/v1/invoices/{reference}

Exceptionally the response is a PDF file.

Example:
$ curl https://protecmail.com/api/v1/invoices/26589 --header "Api-Key: cdd4fc0a-2b4f-4336-90f8-77c72be60791"

< HTTP/1.1 200 OK
{"request_id":"15172f05-20fa-4dcd-acd7-7a59d7bf54be","success":true,"data":[{"ref":5,"date":"2018-10-16T17:04:41+02:00","total":60},{"ref":4,"date":"2018-10-16T15:25:08+02:00","total":720},{"ref":3,"date":"2018-10-15T16:08:04+02:00","total":720},{"ref":1,"date":"2018-10-30T14:36:52.897435613+01:00","total":724.8}]}

Filtering token tanks

This endpoint allows you to know the current number of filtering tokens you have.

GET https://protecmail.com/api/v1/tolens

Returned JSON object in data property:

  • monthly: your monthly tank. It contains remainig tokens of the current month.
  • perm: your permanent tank. It contains previous monthly tokens (thoses which have not been consumed) and your purchased tokens.
  • total: the sum of the two tanks.
Exemple:
$ curl https://protecmail.com/api/v1/tanks --header "Api-Key: cdd4fc0a-2b4f-4336-90f8-77c72be60791"

< HTTP/1.1 200 OK
{"request_id":"9d9866dd-3bc1-4c97-92aa-a27ae812b3b6","success":true,"data":{"monthly":132925,"perm":11086036,"total":11218961}}

Daily consumption

This endpoint returns daily average (based on the last 30 days) of your tokens consumption.

GET https://protecmail.com/api/v1/token/daily-average

The consumption is linked to the data property.

Exemple:
$ curl https://protecmail.com/api/v1/token/daily-average --header "Api-Key: cdd4fc0a-2b4f-4336-90f8-77c72be60791"

< HTTP/1.1 200 OK
{"request_id":"7c4fa265-3287-402e-8f69-1d76c166cfca","success":true,"data":1263}

Get domains list

GET https://protecmail.com/api/v1/domain/all

Example:
$ curl -vvv https://protecmail.com/api/v1/domain/all --header "Api-Key: cdd4fc0a-2b4f-4336-90f8-77c72be60791"

< HTTP/1.1 200 OK
{"request_id":"5b464d9c-0888-4503-92d4-6c2119370140","success":true,"data":["protecmail.com","protecmail.ch","an.tisp.am","wat.tf","goto.pm","truc.tech","test.com"]}

Domain info

GET https://protecmail.com/api/v1/domain/{domain}

The data property of the response is a Domain JSON object with the following structure:

  • domain: domain name Example protecmail.com.
  • redirectTo: IP address or the hostname of the server where we must transmit emails after treatment.
  • spamAction: the action to take if an email is classified as spam. The possible choices are:
    • 0 (default): email is quarantined.
    • 1: email is tagged and then distributed normally.
    Note: this option is not available on the Free plan.
  • virusAction: the action to take if an email is classified as spam. The possible choices are:
    • 0 (default): email is quarantined.
    • 1: email is tagged and then distributed normally.
    Note: this option is not available on the Free plan.
  • sendResume: a boolean that specifies whether summary mails must be sent. Note: this option is not available on the Free plan.
  • resumeTemplateSubject: template for the subject of the quarantine mail. Available only on the Agency plan.
  • resumeTemplateBody: template for the body of the quarantine mail. Available only on the Agency plan.
  • resumeTemplateResume: defines the template used for each mail quarantined. Available only on the Agency plan.
  • resumeLinkHostname: host name to use to generate the quarantine summary mail retrieval links. Available only on the Agency plan.
  • resumeReplyTo: email address to use as sender address for summary e-mails. Available only on the Agency plan.
example:
$ curl https://protecmail.com/api/v1/domain/protecmail.com --header "Api-Key: cdd4fc0a-2b4f-4336-90f8-77c72be60791"

< HTTP/1.1 200 OK
{ "request_id": "4888a255-50c8-4374-95e6-48581f2f967f", "success": true, "data": { "domain": "protecmail.com", "redirectTo": "in.mail.protecmail.com", "spamAction": 0, "virusAction": 0, "sendResume": true }

Add a domain

POST https://protecmail.com/api/v1/domain/{domain}

The body of the request must contain a JSON Domain object.

example:
$ curl https://protecmail.com/api/v1/domais/protecmail.fr --header "Api-Key: cdd4fc0a-2b4f-4336-90f8-77c72be60791" --header "Content-Type: application/json" --request POST --data '{ "domain": "protecmail.fr", "redirectTo": "aspmx.l.google.com", "spamAction": 0, "virusAction": 0, "sendResume": true }'

< HTTP/1.1 200 OK
{ "request_id": "99c73106-a84d-4058-879b-ed3c7873cbb3", "success": true }

Update a domain

PUT https://protecmail.com/api/v1/domain/{domain}

The body of the request must contain a JSON Domain object.

example:
$ curl https://protecmail.com/api/v1/domain/protecmail.fr --header "Api-Key: cdd4fc0a-2b4f-4336-90f8-77c72be60791" --header "Content-Type: application/json" --request PUT --data '{ "domain": "protecmail.fr", "redirectTo": "in.mail.protecmail.com", "spamAction": 0, "virusAction": 0, "sendResume": true }'

< HTTP/1.1 200 OK
{ "request_id": "6df3b97b-7f90-43da-a29f-2eada3ad7d9a", "success": true }

Delete a domain

DELETE https://protecmail.com/api/v1/domains/{domain}

Example:
$ curl https://protecmail.com/api/v1/domain/protecmail.fr --header "Api-Key: cdd4fc0a-2b4f-4336-90f8-77c72be60791" --request DELETE

< HTTP/1.1 200 OK
{ "request_id": "c0616921-bb0b-4a16-8c3f-9dd70df1e2bb", "success": true }

List domain addresses

GET https://protecmail.com/api/v1/domain/{domain}/addresses

Example:
$curl -vvv https://protecmail.com/api/v1/domain/example.tld/addresses --header "Api-Key: cdd4fc0a-2b4f-4336-90f8-77c72be60791"

< HTTP/1.1 200 OK
{"request_id":"7372ded9-bd12-40bf-ac9e-caf8fbb91d50","success":true,"data":["postmaster","john"]}

Add an address

PUT https://protecmail.com/api/v1/domain/{domain}/addresses/{adresse}

Example:
$ curl https://protecmail.com/api/v1/domain/protecmail.fr/addresses/postmaster --header "Api-Key: cdd4fc0a-2b4f-4336-90f8-77c72be60791" --request PUT

< HTTP/1.1 200 OK
{ "request_id": "c0616921-bb0b-4a16-8c3f-9dd70df1e2bb", "success": true }

Remove an address

DELETE https://protecmail.com/api/v1/domain/{domain}/addresses/{adresse}

Example:
$ curl https://protecmail.com/api/v1/domain/protecmail.fr/webmaster --header "Api-Key: cdd4fc0a-2b4f-4336-90f8-77c72be60791" --request DELETE

< HTTP/1.1 200 OK
{ "request_id": "bc4572ef-d16c-4410-aa8e-4405a7eaed32", "success": true }

List quarantined emails

GET https://protecmail.com/api/v1/quarantine/{domaine ou adresse}/{start}/{number of records}

Quarantined mails are returned sorted by date. This means, for example, that if you set '0' to the start setting and 10 to for number of records , information about the last 10 quarantined mails will be returned.

The data property of the response will contain a JSON object with the following structure:

  • emails: the list of quarantined mails with the following properties:
    • date: date (RFC3339).
    • email: email address concerned.
    • domain: domain name concerned.
    • mailfrom: sender address.
    • subject: email subject.
    • ident: email identifier.
  • count: number of quarantined mails concerned.
  • nb_pages: pagination.
  • current_page: current page.
example:
$ curl https://protecmail.com/api/v1/quarantine/protecmail.fr/0/3 --header "Api-Key: cdd4fc0a-2b4f-4336-90f8-77c72be60791"

< HTTP/1.1 200 OK
{ "request_id": "b2cad76e-2402-4a0a-95e5-84c9640afea5", "success": true, "data": { "emails": [ { "date": "2018-06-11T22:49:39+02:00", "email": "xxxx@protecmail.com", "domain": "protecmail.com", "mailfrom": "CanadaExOhrcp@www.Hlawatschek.de", "subject": "Check quality. You will save about 70%. New 10 products weekly. Fast worldwide delivery.", "ident": "11062018224939383525" }, { "date": "2018-06-12T00:38:47+02:00", "email": "xxxx@protecmail.com", "domain": "protecmail.com", "mailfrom": "jpierre.tancogne@protecmail.com", "subject": "tancogne are you from ?", "ident": "12062018003847200251" }, { "date": "2018-06-11T23:57:56+02:00", "email": "xxxx@protecmail.com", "domain": "protecmail.com", "mailfrom": "ID-343912webmaster@localhost", "subject": "Segue o parecer do seu rastreio 20180077923 Data: 11/06/2018", "ident": "11062018235756594497" } ], "count": 1724, "nb_pages": 575, "current_page": 1 }

Resend a quarantined mail

GET https://protecmail.com/api/v1/quarantine/{ident}

Example:
$ curl https://protecmail.com/api/v1/quarantine/11062018225433918076 --header "Api-Key: cdd4fc0a-2b4f-4336-90f8-77c72be60791"

< HTTP/1.1 200 OK
{ "request_id": "3e144514-ed9d-41b0-aaa4-53f44ddd22cd", "success": true }