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.
- 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.
- 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
}