Update library to support TacoMail API v2

.github/workflows/tests.yml

@@ -0,0 +1,32 @@
+name: Tests
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+
+      - name: Set up Python
+        run: uv python install 3.12
+
+      - name: Install dependencies
+        run: uv sync --group dev
+
+      - name: Run linter
+        run: uv run ruff check .
+
+      - name: Run tests
+        env:
+          POSTMARK_API_TOKEN: ${{ secrets.POSTMARK_API_TOKEN }}
+          SENDER_EMAIL: ${{ secrets.SENDER_EMAIL }}
+        run: uv run pytest tests/ -v

API.md

@@ -1,11 +1,53 @@
 # TacoMail API
 TacoMail provides an API which may be incorporated by third-party developers. This document describes the available routes. All mails will be automatically deleted after one hour.
 
+The base URL for all requests is `https://tacomail.de`.
+
+## Creating an inbox session
+Only incoming mails with an associated inbox session are saved. A session is valid for a configured time and can be renewed by posting to the same endpoint again.
+
+```
+POST /api/v2/session
+```
+**Body**
+```
+{
+    "username": string,
+    "domain": string
+}
+```
+Expected status: 200
+
+### Example response
+```json
+{
+    "expires": 1756229705148,
+    "username": "axolotl_friend",
+    "domain": "tacomail.de"
+}
+```
+
+## Deleting an inbox session
+Deleting an inbox session will cause any incoming mails associated with the session's address to be rejected. It does not delete already saved mails. See *Deleting a single mail* and *Deleting an entire inbox* for this purpose.
+
+```
+DELETE /api/v2/session
+```
+**Body**
+```
+{
+    "username": string,
+    "domain": string
+}
+```
+Expected status: 200
+
 ## Fetching the contact email address
 Returns the contact email address of this instance.
 ```
-GET /api/v1/contactEmail
+GET /api/v2/contactEmail
 ```
+Expected status: 200
 
 ### Example response
 ```json
@@ -17,7 +59,7 @@ GET /api/v1/contactEmail
 ## Fetching a random username
 Returns a random username.
 ```
-GET /api/v1/randomUsername
+GET /api/v2/randomUsername
 ```
 
 ### Example response
@@ -30,7 +72,7 @@ GET /api/v1/randomUsername
 ## Fetching all available domains
 Returns an array of available domains.
 ```
-GET /api/v1/domains
+GET /api/v2/domains
 ```
 Expected status: 200
 
@@ -45,7 +87,7 @@ Expected status: 200
 ## Fetching mails of an inbox
 Returns the last 10 mails received by an inbox. An optional `limit` query parameter may be used to reduce the amount of mails returned. The maximum is 10.
 ```
-GET /api/v1/mail/:address
+GET /api/v2/mail/:address
 ```
 Expected status: 200
 
@@ -83,7 +125,7 @@ Expected status: 200
 ## Fetching a single mail
 Returns the data of a single mail identified by the recipient and its ID.
 ```
-GET /api/v1/mail/:address/:mailId
+GET /api/v2/mail/:address/:mailId
 ```
 Expected status: 200
 
@@ -117,9 +159,9 @@ Expected status: 200
 ```
 
 ## Fetching attachments
-Returns with the ID and name of all attachments of a mail. The `present` field indicates whether the attachment can be downloaded. Attachments will only be saved until their total sizes exceeds the configured `maxAttachmentsSize`.
+Returns the ID and name of all attachments of a mail. The `present` field indicates whether the attachment can be downloaded. Attachments will only be saved until their total sizes exceed the configured `maxAttachmentsSize`.
 ```
-GET /api/v1/mail/:address/:mailId/attachments
+GET /api/v2/mail/:address/:mailId/attachments
 ```
 Expected status: 200
 
@@ -134,23 +176,23 @@ Expected status: 200
 ]
 ```
 
-## Download an attachment
+## Downloading an attachment
 Downloads a single attachment of a mail. Make sure the `present` field is set to `true`.
 ```
-GET /api/v1/mail/:address/:mailId/attachments/:attachmentId
+GET /api/v2/mail/:address/:mailId/attachments/:attachmentId
 ```
 Expected status: 200
 
-## Delete a single mail
+## Deleting a single mail
 Deletes a single mail and its attachments from the server.
 ```
-DELETE /api/v1/mail/:address/:mailId
+DELETE /api/v2/mail/:address/:mailId
 ```
 Expected status: 204
 
-## Delete inbox
-Deleted all mails from the inbox.
+## Deleting an entire inbox
+Deletes an entire inbox and all mails inside it.
 ```
-DELETE /api/v1/mail/:address
+DELETE /api/v2/mail/:address
 ``` 
 Expected status: 204

README.md

@@ -30,6 +30,10 @@ with TacomailClient() as client:
     domains = client.get_domains()
     email_address = f"{username}@{domains[0]}"
 
+    # Create a session to receive emails (required for API v2)
+    session = client.create_session(username, domains[0])
+    print(f"Session expires at: {session.expires}")
+
     # Wait for an email to arrive
     email = client.wait_for_email(email_address, timeout=30)
     if email:
@@ -47,7 +51,12 @@ from tacomail import AsyncTacomailClient
 async def main():
     async with AsyncTacomailClient() as client:
         # Get a random email address
-        email_address = await client.get_random_address()
+        username = await client.get_random_username()
+        domains = await client.get_domains()
+        email_address = f"{username}@{domains[0]}"
+
+        # Create a session to receive emails (required for API v2)
+        session = await client.create_session(username, domains[0])
 
         # Wait for an email with specific subject
         def filter_email(email):
@@ -75,11 +84,14 @@ asyncio.run(main())
 - `EmailAddress`: Dataclass for email addresses
 - `EmailBody`: Dataclass for email content
 - `Attachment`: Dataclass for email attachments
+- `Session`: Dataclass for inbox session information
 
 ### Common Methods
 
 Both sync and async clients provide these methods:
 
+- `create_session(username, domain)`: Create an inbox session to receive emails
+- `delete_session(username, domain)`: Delete an inbox session
 - `get_random_username()`: Generate a random username
 - `get_domains()`: Get list of available domains
 - `get_random_address()`: Get a complete random email address

src/tacomail/__init__.py

@@ -5,6 +5,7 @@
     EmailAddress,
     EmailBody,
     Attachment,
+    Session,
 )
 
 __all__ = [
@@ -14,4 +15,5 @@
     "EmailBody",
     "Attachment",
     "AsyncTacomailClient",
+    "Session",
 ]