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
                    }