The Locker Private Email API is organized around REST. These APIs return JSON responses and uses standard HTTP Response codes, authentication, and verbs.
\nThese APIs are used on Locker Password Manager (https://locker.io).
\nBase API Host
\n\nThe Locker API uses a Bearer token to authenticate requests. All APIs need to be authenticated by your API Key. This API Key is a JWT token with cs. prefix. After you upgrade your plan, you can get your API Key at Locker ID (https://id.locker.io/api-key).
One example API Key:
\nBearer cs.eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VyIjoiMjMyM0Bwdy5jeXN0YWNrLm9yZyIsImNyZWF0ZWRfdGltZSI6MTY0MDYxNzAzNSwiZXhwaXJlZF90aW1lIjoxNjQwNjMxNDM1LCJ0b2tlbl90eXBlIjoiYXV0aGVudGljYXRpb24iLCJzY29wZSI6InB3ZG1hbmFnZXIifQ.xxxxxxxxxxxxxxxxxxxxxxxx_PrivateXXXX\n\nThe Private Email API uses conventional HTTP response codes to indicate the success or failure of an API request. In general:
\nCode 2xx range indicates success
Code in 4xx range indicates an error that failed given the information provided (e.g, a required parameter was omitted, authentication failed, etc.). Almost 4xx errors have the format as:
{\n \"code\": \"0000\",\n \"message\": \"xxx\",\n \"details\": {} \n}\n\n* code (string) This is an error code
* message (string) Error description
* details (object) An object indicates details of this error
Code in 5xx range indicates an error with our servers.
All top-level API resources have support for bulk fetch via \"list\" API methods. These list API methods share a common structure, taking these parameters: page, size, paging.
* page (optional, default is 1): The current index of \"list\"
* size (optional, default is 10): A limit on the number of objects to be returned. Only some APIs support this parameter
* paging (optional, default is 1): Paging or not. Only some APIs support this parameter
To keep incoming traffic under control and maintain a great experience for all our users, our API is behind a rate limiter. Users who send many requests in quick succession may see error responses that show up as status code 429.
\n","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","toc":[{"content":"Authentication","slug":"authentication"},{"content":"Errors","slug":"errors"},{"content":"Pagination","slug":"pagination"},{"content":"Rate limit","slug":"rate-limit"}],"owner":"22756764","collectionId":"74b4a7f8-7e09-44db-b70d-0de084dcbddd","publishedId":"2s7ZE4KjKU","public":true,"customColor":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"EF5B25"},"publishDate":"2022-09-22T08:05:24.000Z"},"item":[{"name":"Private Email Addresses","item":[{"name":"List addresses","id":"ab93749d-a401-4cb7-bdbf-90c9bc08f64f","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[{"key":"Authorization","value":"Bearer {{api_key}}","type":"text"}],"url":"{{host}}/v3/relay/addresses","description":"Returns
\nA dictionary with a results property that contains Private Email objects if the paging parameter value is 1. Else, this API returns a list of Private Email objects.
If no more Private Email objects are available, the resulting array will be empty. This request should never raise an error.
The page param. Default is 1
\n","type":"text/plain"},"key":"page","value":"1"},{"disabled":true,"description":{"content":"Paging or not. if value is 1, the result will be paginated. Default is 0
\n","type":"text/plain"},"key":"paging","value":"0"},{"disabled":true,"description":{"content":"Page size param. Default is 10
\n","type":"text/plain"},"key":"size","value":"10"}],"variable":[]}},"response":[{"id":"c87756fa-822e-4db9-add1-eec0e8737b31","name":"Get list addresses successfully","originalRequest":{"method":"GET","header":[{"key":"Authorization","value":"Bearer {{api_key}}","type":"text"}],"url":{"raw":"{{host}}/v3/relay/addresses","host":["{{host}}"],"path":["v3","relay","addresses"],"query":[{"key":"page","value":"1","description":"The page param. Default is 1","disabled":true},{"key":"paging","value":"1","description":"Paging or not. if value is 1, the result will be paginated. Default is 0","disabled":true},{"key":"size","value":"10","description":"Page size param. Default is 10","disabled":true}]}},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"},{"key":"Allow","value":"GET, POST, HEAD, OPTIONS"},{"key":"Content-Length","value":"319"}],"cookie":[],"responseTime":null,"body":"{\n \"count\": 1,\n \"next\": null,\n \"previous\": null,\n \"results\": [\n {\n \"id\": 1,\n \"address\": \"mycustomalias\",\n \"enabled\": false,\n \"block_spam\": true,\n \"description\": \"\",\n \"created_time\": 1657159423.0,\n \"updated_time\": 1663832574.0,\n \"num_forwarded\": 1,\n \"num_blocked\": 0,\n \"num_replied\": 0,\n \"num_spam\": 0,\n \"domain\": \"maily.org\",\n \"subdomain\": null,\n \"full_address\": \"mycustomalias@maily.org\"\n }\n ]\n}"}],"_postman_id":"ab93749d-a401-4cb7-bdbf-90c9bc08f64f"},{"name":"Generate new address","id":"fe82f9ec-e205-4466-b81c-05accdbed6be","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"Authorization","value":"Bearer {{api_key}}","type":"text"}],"body":{"mode":"raw","raw":"","options":{"raw":{"language":"json"}}},"url":"{{host}}/v3/relay/addresses","description":"Create a new Private Email object. This API does not require any body data.
\nReturns
\nReturn a Private Email object if the request is successful
\n","urlObject":{"path":["v3","relay","addresses"],"host":["{{host}}"],"query":[],"variable":[]}},"response":[{"id":"0c3f05a9-a632-43a3-934e-4c17794308c0","name":"Generate new address successfully","originalRequest":{"method":"POST","header":[{"key":"Authorization","value":"Bearer {{api_key}}","type":"text"}],"body":{"mode":"raw","raw":"","options":{"raw":{"language":"json"}}},"url":"https://api.locker.io/v3/relay/addresses"},"status":"Created","code":201,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"},{"key":"Allow","value":"GET, POST, HEAD, OPTIONS"},{"key":"Content-Length","value":"261"}],"cookie":[],"responseTime":null,"body":"{\n \"id\": 6,\n \"address\": \"16pv4a\",\n \"enabled\": true,\n \"block_spam\": false,\n \"description\": \"\",\n \"created_time\": 1663832455,\n \"updated_time\": null,\n \"num_forwarded\": 0,\n \"num_blocked\": 0,\n \"num_replied\": 0,\n \"num_spam\": 0,\n \"domain\": \"maily.org\",\n \"subdomain\": null,\n \"full_address\": \"16pv4a@maily.org\"\n}"}],"_postman_id":"fe82f9ec-e205-4466-b81c-05accdbed6be"},{"name":"Update relay address","id":"b4ec41e2-5354-41e0-8142-e79820116141","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"PUT","header":[{"key":"Authorization","value":"Bearer {{api_key}}","type":"text"}],"body":{"mode":"raw","raw":"{\n \"address\": \"mycustomalias\",\n \"enabled\": true,\n \"block_spam\": false\n}","options":{"raw":{"language":"json"}}},"url":"{{host}}/v3/relay/addresses/:address_id","description":"Updates the private email by settings the values of the parameters passed. You can only update the first private email address.
\nBody data
\nReturns
\nReturn HTTP Status code 200 with id of the updated private email
The private email id
\n","type":"text/plain"},"type":"any","value":"1","key":"address_id"}]}},"response":[{"id":"cfb2f812-4007-4e98-bc26-75e630606f26","name":"Update relay address successfully","originalRequest":{"method":"PUT","header":[{"key":"Authorization","value":"Bearer {{api_key}}","type":"text"}],"body":{"mode":"raw","raw":"{\n \"address\": \"mycustomalias\",\n \"enabled\": true,\n \"block_spam\": false\n}","options":{"raw":{"language":"json"}}},"url":{"raw":"{{host}}/v3/relay/addresses/:address_id","host":["{{host}}"],"path":["v3","relay","addresses",":address_id"],"variable":[{"key":"address_id","value":"1","description":"The private email id"}]}},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"},{"key":"Allow","value":"GET, PUT, DELETE, HEAD, OPTIONS"},{"key":"Content-Length","value":"8"}],"cookie":[],"responseTime":null,"body":"{\n \"id\": 1\n}"}],"_postman_id":"b4ec41e2-5354-41e0-8142-e79820116141"},{"name":"Turn on/off Block spam","id":"989f596a-6a5a-4a51-9bc4-18f4c4a05457","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"PUT","header":[{"key":"Authorization","value":"Bearer {{api_key}}","type":"text"}],"body":{"mode":"raw","raw":"","options":{"raw":{"language":"json"}}},"url":"{{host}}/v3/relay/addresses/:address_id/block_spam","description":"You can use this API to turn on or turn off the block spam feature. It does not require any body data.
\nReturns
\nReturn HTTP status code 200 with:
\nThe private email id
\n","type":"text/plain"},"type":"any","value":"1","key":"address_id"}]}},"response":[{"id":"4932d92f-5783-49b0-97d7-00b5e5018d73","name":"Turn on/off Block spam","originalRequest":{"method":"PUT","header":[{"key":"Authorization","value":"Bearer {{api_key}}","type":"text"}],"body":{"mode":"raw","raw":"","options":{"raw":{"language":"json"}}},"url":{"raw":"{{host}}/v3/relay/addresses/:address_id/block_spam","host":["{{host}}"],"path":["v3","relay","addresses",":address_id","block_spam"],"variable":[{"key":"address_id","value":"1","description":"The private email id"}]}},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"},{"key":"Allow","value":"PUT, OPTIONS"},{"key":"Content-Length","value":"26"}],"cookie":[],"responseTime":null,"body":"{\n \"id\": 1,\n \"block_spam\": true\n}"}],"_postman_id":"989f596a-6a5a-4a51-9bc4-18f4c4a05457"},{"name":"Enable/Disable","id":"abedfc1a-ed02-48c5-910c-4a077ae9cb80","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"PUT","header":[{"key":"Authorization","value":"Bearer {{api_key}}","type":"text"}],"body":{"mode":"raw","raw":"","options":{"raw":{"language":"json"}}},"url":"{{host}}/v3/relay/addresses/:address_id/enabled","description":"You can use this API to enable or disable your Private Email.
\nReturns
\nThe private email id
\n","type":"text/plain"},"type":"any","value":"1","key":"address_id"}]}},"response":[{"id":"3f394e9d-ea40-43e7-a59f-9667617cafcb","name":"Enable/Disable","originalRequest":{"method":"PUT","header":[{"key":"Authorization","value":"Bearer {{api_key}}","type":"text"}],"body":{"mode":"raw","raw":"","options":{"raw":{"language":"json"}}},"url":{"raw":"{{host}}/v3/relay/addresses/:address_id/enabled","host":["{{host}}"],"path":["v3","relay","addresses",":address_id","enabled"],"variable":[{"key":"address_id","value":"1"}]}},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"},{"key":"Allow","value":"PUT, OPTIONS"},{"key":"Content-Length","value":"24"}],"cookie":[],"responseTime":null,"body":"{\n \"id\": 1,\n \"enabled\": false\n}"}],"_postman_id":"abedfc1a-ed02-48c5-910c-4a077ae9cb80"},{"name":"Delete an address","id":"8970ef9b-ee88-4277-91e5-431f8027aae2","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"DELETE","header":[{"key":"Authorization","value":"Bearer {{api_key}}","type":"text"}],"body":{"mode":"raw","raw":"","options":{"raw":{"language":"json"}}},"url":"{{host}}/v3/relay/addresses/:address_id","description":"Delete a private email. If you delete a private email, you will not receive any email in the future and you will not re-create this email alias.
\nReturns
\nReturn HTTP status code 204
\n","urlObject":{"path":["v3","relay","addresses",":address_id"],"host":["{{host}}"],"query":[],"variable":[{"id":"eac04742-034a-4cfe-bc3d-e9383ef3b4ee","description":{"content":"The private email id
\n","type":"text/plain"},"type":"any","value":"6","key":"address_id"}]}},"response":[{"id":"bb3e71ad-f6ae-4e7c-8b89-61ef35486b13","name":"Delete an address","originalRequest":{"method":"DELETE","header":[{"key":"Authorization","value":"Bearer cs.eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VyIjoia2hhaS50cmFucXVhbmcuODcuOTdAZ21haWwuY29tIiwiY3JlYXRlZF90aW1lIjoxNjU5OTMyMjMzLCJleHBpc...","type":"text"}],"body":{"mode":"raw","raw":"","options":{"raw":{"language":"json"}}},"url":{"raw":"https://api.locker.io/v3/relay/addresses/:address_id","protocol":"https","host":["api","locker","io"],"path":["v3","relay","addresses",":address_id"],"variable":[{"key":"address_id","value":"6","description":"The private email id"}]}},"status":"No Content","code":204,"_postman_previewlanguage":"plain","header":[{"key":"Content-Length","value":"0"},{"key":"Allow","value":"GET, PUT, DELETE, HEAD, OPTIONS","description":"","type":"text"}],"cookie":[],"responseTime":null,"body":""}],"_postman_id":"8970ef9b-ee88-4277-91e5-431f8027aae2"}],"id":"b5f9ee50-61eb-44b3-a1a9-3d42a3875caa","description":"Private Email object represent your private email. You can use them to forward messages to your true email. Use them to protect your online accounts and you can receive only the messages you want in your inbox.
\nPrivate Email object
\nReturns
This API returns a list of Private Email Subdomain objects.
If no more subdomain objects are available, the resulting array will be empty. This request should never raise an error.
Create a new subdomain. Each user only creates one subdomain.
\nBody data
\nReturns
\nIf the request is successful, it returns Private Email Subdomain object.
\nIf the response return 400 status code with code is 8001, that means you can't\ncreate new subdomain because the number of subdomain is reached
Change your subdomain.
\nBody data
\n* subdomain (string) New subdomain of the Private Email Subdomain object
\nReturns
\nReturn HTTP status 200 with id of the updated object
The subdomain id
\n","type":"text/plain"},"type":"any","value":"2","key":"id"}]}},"response":[{"id":"0905fcac-6658-42e6-9bff-6f80a2a2ee7c","name":"Update successfully","originalRequest":{"method":"PUT","header":[{"key":"Authorization","value":"Bearer cs.eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VyIjoia2hhaS50cmFucXVhbmcuODcuOTdAZ21haWwuY29tIiwiY3JlYXRlZF90aW1lIjoxNjU5OTMyMjMzLCJleHBpc...","type":"text"}],"body":{"mode":"raw","raw":"{\r\n \"subdomain\": \"mysubdomain2\"\r\n}","options":{"raw":{"language":"json"}}},"url":{"raw":"https://api.locker.io/v3/relay/subdomains/:id","protocol":"https","host":["api","locker","io"],"path":["v3","relay","subdomains",":id"],"variable":[{"key":"id","value":"2","description":"The subdomain id"}]}},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"},{"key":"Allow","value":"GET, PUT, DELETE, HEAD, OPTIONS"},{"key":"Content-Length","value":"8"}],"cookie":[],"responseTime":null,"body":"{\n \"id\": 2\n}"}],"_postman_id":"f4b25c87-cc1f-4fff-8761-452408915c2b"},{"name":"Delete the subdomain","id":"e440e712-23ef-49f1-b2c6-f36fd84fe9db","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"DELETE","header":[{"key":"Authorization","value":"Bearer {{api_key}}","type":"text"}],"body":{"mode":"raw","raw":"","options":{"raw":{"language":"json"}}},"url":"{{host}}/v3/relay/subdomains/:id","description":"Delete a subdomain.
\nReturns
\nReturn HTTP status code 204
\n","urlObject":{"path":["v3","relay","subdomains",":id"],"host":["{{host}}"],"query":[],"variable":[{"id":"c59853e6-b386-4a4a-8fa8-888e6e8aab40","description":{"content":"The subdomain id
\n","type":"text/plain"},"type":"any","value":"2","key":"id"}]}},"response":[{"id":"2fd5c072-9a48-49d7-82bb-bb10649572ac","name":"Delete the subdomain successfully","originalRequest":{"method":"DELETE","header":[{"key":"Authorization","value":"Bearer cs.eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VyIjoia2hhaS50cmFucXVhbmcuODcuOTdAZ21haWwuY29tIiwiY3JlYXRlZF90aW1lIjoxNjU5OTMyMjMzLCJleHBpc...","type":"text"}],"body":{"mode":"raw","raw":"","options":{"raw":{"language":"json"}}},"url":{"raw":"https://api.locker.io/v3/relay/subdomains/:id","protocol":"https","host":["api","locker","io"],"path":["v3","relay","subdomains",":id"],"variable":[{"key":"id","value":"2","description":"The subdomain id"}]}},"status":"No Content","code":204,"_postman_previewlanguage":"plain","header":[{"key":"Allow","value":"GET, PUT, DELETE, HEAD, OPTIONS"},{"key":"Content-Length","value":"0"}],"cookie":[],"responseTime":null,"body":""}],"_postman_id":"e440e712-23ef-49f1-b2c6-f36fd84fe9db"},{"name":"Check use subdomain or not","id":"a99aced5-357f-4f64-9a77-69f7cfb5206a","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[{"key":"Authorization","value":"Bearer {{api_key}}","type":"text"}],"url":"{{host}}/v3/relay/subdomains/use_subdomain","description":"Check you use subdomain to generate new Private Email or not?
\nReturns
\nTurn on or turn off the using domain feature when user creates new Private Email object.
\nBody data
\n* use_relay_subdomain (bool) Use subdomain or not
\nReturns
\n* use_relay_subdomain (bool) Use subdomain or not
\n","urlObject":{"path":["v3","relay","subdomains","use_subdomain"],"host":["{{host}}"],"query":[],"variable":[]}},"response":[{"id":"c0c8f1c1-3445-49c8-b595-e83264e2c0e6","name":"Use subdomains","originalRequest":{"method":"PUT","header":[{"key":"Authorization","value":"Bearer {{api_key}}","type":"text"}],"body":{"mode":"raw","raw":"{\r\n \"use_relay_subdomain\": true\r\n}","options":{"raw":{"language":"json"}}},"url":"{{host}}/v3/relay/subdomains/use_subdomain"},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"},{"key":"Allow","value":"GET, PUT, HEAD, OPTIONS"},{"key":"Content-Length","value":"29"}],"cookie":[],"responseTime":null,"body":"{\n \"use_relay_subdomain\": true\n}"}],"_postman_id":"a7d8eacd-89c6-46d7-908a-3d7d76536b8c"}],"id":"5e337dd7-5c6b-4627-881b-05bd356534cc","description":"Private Email Subdomains represent the subdomains of the Private Email object. This feature is only available to Premium users.
\nThe Subdomain object
\n* id (int) The id of the subdomain\n* subdomain (string) Subdomain of the Private Email
\n","_postman_id":"5e337dd7-5c6b-4627-881b-05bd356534cc"}]}