{"id":24441732,"url":"https://github.com/gerold-penz/gp-imap-rest-api","last_synced_at":"2025-07-17T18:16:27.431Z","repository":{"id":263790755,"uuid":"863649143","full_name":"gerold-penz/gp-imap-rest-api","owner":"gerold-penz","description":"IMAP REST API with Bun und SvelteKit","archived":false,"fork":false,"pushed_at":"2025-03-15T08:53:28.000Z","size":148,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-30T14:28:11.724Z","etag":null,"topics":["api","bun","docker","imap","imapflow","postal-mime","rest","server","sveltekit","typescript"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/gerold-penz.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-09-26T16:57:36.000Z","updated_at":"2025-03-15T08:53:31.000Z","dependencies_parsed_at":"2024-11-20T11:43:21.604Z","dependency_job_id":null,"html_url":"https://github.com/gerold-penz/gp-imap-rest-api","commit_stats":null,"previous_names":["gerold-penz/gp-imap-rest-api"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gerold-penz%2Fgp-imap-rest-api","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gerold-penz%2Fgp-imap-rest-api/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gerold-penz%2Fgp-imap-rest-api/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gerold-penz%2Fgp-imap-rest-api/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/gerold-penz","download_url":"https://codeload.github.com/gerold-penz/gp-imap-rest-api/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251721164,"owners_count":21632774,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api","bun","docker","imap","imapflow","postal-mime","rest","server","sveltekit","typescript"],"created_at":"2025-01-20T21:19:21.546Z","updated_at":"2025-04-30T14:28:21.537Z","avatar_url":"https://github.com/gerold-penz.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Gp-Imap-Rest-Api\n\nThis is a small program that can be executed via Docker. \nThe calls are passed as HTTP requests.\nThe return is always a JSON string.\nThis program is based on the wonderful work of \n[ImapFlow](https://github.com/postalsys/imapflow) and \n[Postal-Mime](https://github.com/postalsys/postal-mime).\n\nWhat can the program do so far?\n\n- List all IMAP mailboxes.\n- List the UIDs of all messages in a mailbox.\n- Parse and return a message including attachments (Base64 encoded).\n\nThis is all the program can do at the moment, but further functions are planned.\n\n\n## Docker-Compose File\n\nThis Docker Compose file is all you need to start the server.\nNo data is saved.\n\n_docker-compose.yaml:_\n\n```yaml\nservices:\n  gp-imap-rest-api:\n    image: ghcr.io/gerold-penz/gp-imap-rest-api\n    ports:\n      - \"3000:3000\"\n```\n\n\n## Data storage\n\n**No data is saved.**\nEach request must contain the credentials to the IMAP server in the header.\n\n\n## HTTP Header\nwith IMAP credentials\n\nEvery HTTP request to the “Gp-Imap-Rest-Api Server” must contain the \naccess data to the IMAP server.\nTo ensure that this is not transferred in plain text, \nthis access data must be transferred in the HTTP header.\nIf HTTPS is used, the header is transmitted to the server in encrypted form.\n\nThe header entries required for this all start with `X-Imap-`.\n\n### X-Imap Headers\n\nDescriptions taken from the \n[documentation of ImapFlow](https://imapflow.com/module-imapflow-ImapFlow.html)\n\n_Example:_\n```http request\nX-Imap-Host: imap.example.com\nX-Imap-Port: 993\nX-Imap-Secure: true\nX-Imap-User: exampleuser@example.com\nX-Imap-Pass: examplePassword123\n```\n\n#### X-Imap-Host\n\nHostname of the IMAP server\n\n\n#### X-Imap-Port\n\nPort number for the IMAP server\n\n\n#### X-Imap-Secure\n\n`true|false`\n\n_optional_, Default: false\n\nShould the connection be established over TLS.\nIf `false` then connection is upgraded to TLS using STARTTLS \nextension before authentication.\n\n\n#### X-Imap-Servername\n\n_optional_\n\nServername for SNI (or when host is set to an IP address).\n\n\n#### X-Imap-Disable-Compression\n\n`true|false`\n\n_optional_, Default: false\n\nIf `true` then client does not try to use COMPRESS=DEFLATE extension.\n\n\n#### X-Imap-User\n\nUsername for plain-text authentication.\n\n\n#### X-Imap-Pass\n\n_optional_\n\nPassword for plain-text authentication.\n\n\n#### X-Imap-Access-Token\n\n_optional_\n\nOAuth2 Access Token, if using OAuth2 authentication.\n\n\n#### X-Imap-Disable-Auto-Idle\n\n`true|false`\n\n_optional_, Default: false\n\nIf `true` then IDLE is not started automatically.\nUseful if you only need to perform specific tasks over the connection\n\n\n#### X-Imap-Tls-Reject-Unauthorized\n\n`true|false`\n\n_optional_, Default: true\n\nIf `false` then client accepts self-signed and expired \ncertificates from the server.\n\n\n## Usage\n\n\n### Get all mailboxes\n\n```http\nGET https://\u003cServer URL\u003e/api/mailboxes/\nX-Imap-Host: \u003cIMAP_HOST\u003e\nX-Imap-Port: \u003cIMAP_PORT\u003e\nX-Imap-Secure: \u003cIMAP_SECURE\u003e\nX-Imap-User: \u003cIMAP_USER\u003e\nX-Imap-Pass: \u003cIMAP_PASS\u003e\n```\n\n#### Example\n\n```http request\nGET https://gp-imap-rest-api.gerold-penz.at/api/mailboxes/\nX-Imap-Host: imap.example.com\nX-Imap-Port: 993\nX-Imap-Secure: true\nX-Imap-User: exampleuser@example.com\nX-Imap-Pass: examplePassword123\n```\n\n```shell\ncurl --request GET \\\n  --url https://gp-imap-rest-api.gerold-penz.at/api/mailboxes/ \\\n  --header 'X-Imap-Host: imap.example.com' \\\n  --header 'X-Imap-Port: 993' \\\n  --header 'X-Imap-Secure: true' \\\n  --header 'X-Imap-User: exampleuser@example.com' \\\n  --header 'X-Imap-Pass: examplePassword123'\n```\n\n_Response:_\n\n```json\n{\n  \"success\": true,\n  \"mailboxes\": [\n    {\n      \"path\": \"INBOX\",\n      \"pathAsListed\": \"INBOX\",\n      \"flags\": [\n        \"\\\\HasNoChildren\"\n      ],\n      \"delimiter\": \"/\",\n      \"listed\": true,\n      \"parentPath\": \"\",\n      \"parent\": [],\n      \"name\": \"INBOX\",\n      \"subscribed\": true,\n      \"specialUse\": \"\\\\Inbox\",\n      \"specialUseSource\": \"name\"\n    },\n    {\n      \"path\": \"Sent\",\n      \"pathAsListed\": \"Sent\",\n      \"flags\": [\n        \"\\\\HasNoChildren\",\n        \"\\\\UnMarked\",\n        \"\\\\Sent\"\n      ],\n      \"delimiter\": \"/\",\n      \"listed\": true,\n      \"parentPath\": \"\",\n      \"parent\": [],\n      \"name\": \"Sent\",\n      \"subscribed\": true,\n      \"specialUse\": \"\\\\Sent\",\n      \"specialUseSource\": \"extension\"\n    }\n  ]\n}\n```\n\n\n### Get all message UIDs of one mailbox\n\n```http\nGET https://\u003cServer URL\u003e/api/mailboxes/\u003cMailbox Path\u003e\nX-Imap-Host: \u003cIMAP_HOST\u003e\nX-Imap-Port: \u003cIMAP_PORT\u003e\nX-Imap-Secure: \u003cIMAP_SECURE\u003e\nX-Imap-User: \u003cIMAP_USER\u003e\nX-Imap-Pass: \u003cIMAP_PASS\u003e\n```\n\n#### Example\n\n```http request\nGET https://gp-imap-rest-api.gerold-penz.at/api/mailboxes/INBOX\nX-Imap-Host: imap.example.com\nX-Imap-Port: 993\nX-Imap-Secure: true\nX-Imap-User: exampleuser@example.com\nX-Imap-Pass: examplePassword123\n```\n\n```shell\ncurl --request GET \\\n  --url https://gp-imap-rest-api.gerold-penz.at/api/mailboxes/INBOX \\\n  --header 'X-Imap-Host: imap.example.com' \\\n  --header 'X-Imap-Port: 993' \\\n  --header 'X-Imap-Secure: true' \\\n  --header 'X-Imap-User: exampleuser@example.com' \\\n  --header 'X-Imap-Pass: examplePassword123'\n```\n\n_Response:_\n\n```json\n{\n  \"success\": true,\n  \"uids\": [\n    17563,\n    17684,\n    17685,\n    17686,\n    17701,\n    17703,\n    17704,\n    17711\n  ],\n  \"total\": 8\n}\n```\n\n\n### Get parsed message with attachments\n\n```http\nGET https://\u003cServer URL\u003e/api/mailboxes/\u003cMailbox Path\u003e/messages/\u003cMessage UID\u003e\nX-Imap-Host: \u003cIMAP_HOST\u003e\nX-Imap-Port: \u003cIMAP_PORT\u003e\nX-Imap-Secure: \u003cIMAP_SECURE\u003e\nX-Imap-User: \u003cIMAP_USER\u003e\nX-Imap-Pass: \u003cIMAP_PASS\u003e\n```\n\n#### Example\n\n```http request\nGET https://gp-imap-rest-api.gerold-penz.at/api/mailboxes/INBOX/messages/1234\nX-Imap-Host: imap.example.com\nX-Imap-Port: 993\nX-Imap-Secure: true\nX-Imap-User: exampleuser@example.com\nX-Imap-Pass: examplePassword123\n```\n\n```shell\ncurl --request GET \\\n  --url https://gp-imap-rest-api.gerold-penz.at/api/mailboxes/INBOX/messages/1234 \\\n  --header 'X-Imap-Host: imap.example.com' \\\n  --header 'X-Imap-Port: 993' \\\n  --header 'X-Imap-Secure: true' \\\n  --header 'X-Imap-User: exampleuser@example.com' \\\n  --header 'X-Imap-Pass: examplePassword123'\n```\n\n## Usage inside a N8N workflow\n\n![N8N workflow](images/n8n-workflow.png)\n\nThe \"Get parsed message\" node is the HTML request which \nuses the Gp-Imap-Rest-Api to fetch the attachments.\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgerold-penz%2Fgp-imap-rest-api","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgerold-penz%2Fgp-imap-rest-api","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgerold-penz%2Fgp-imap-rest-api/lists"}