{ "openapi": "3.0.0", "info": { "title": "Forward Email API", "description": "\"\"/
Welcome to the comprehensive API documentation for Forward Email. This API allows you to manage email forwarding, domains, aliases, outbound emails, and more programmatically.\n\n## Key Features\n* **Domain Management:** Create, retrieve, update, delete, and verify domains.\n* **Alias Management:** Manage email aliases, including creation, updates, and recipient management.\n* **Outbound SMTP:** Send emails via SMTP, manage limits, and track sent emails.\n* **Account & Logs:** Manage your account details and download activity logs.\n* **Security:** Encrypt TXT records and manage domain members/invites.\n* **CardDAV Contacts:** Full CRUD operations for contact management with vCard support.\n* **CalDAV Calendars:** Complete calendar management with timezone and color support.\n* **IMAP/POP3 Messages:** Comprehensive message management with advanced search capabilities.\n* **IMAP/POP3 Folders:** Full folder management including creation, renaming, and deletion.\n\n## Authentication\nMost endpoints require authentication using your **API Key**. Provide the API Key as the `username` in the Basic Authentication header, leaving the password empty.\n\n```http\nAuthorization: Basic QVBJX1RPS0VOOg==\n```\n(Replace `API_TOKEN` with your actual key before Base64 encoding)\n\nEndpoints related to **Alias Contacts, Calendars, Messages, and Folders** require a generated alias username and password for Basic Authentication.\n\n## Errors\nThe API uses standard HTTP status codes to indicate success or failure. Error responses include a JSON body with a `message` field detailing the error.\n\n| Status Code | Meaning |\n|-------------|---------------------|\n| 200 | OK |\n| 400 | Bad Request |\n| 401 | Unauthorized |\n| 403 | Forbidden |\n| 404 | Not Found |\n| 409 | Conflict |\n| 412 | Precondition Failed |\n| 429 | Too Many Requests |\n| 500 | Internal Server Error|\n| 501 | Not Implemented |\n| 502 | Bad Gateway |\n| 503 | Service Unavailable |\n| 504 | Gateway Time-out |\n\n*If you encounter a `5xx` error, please contact [api@forwardemail.net](mailto:api@forwardemail.net).*\n\n## Localization\nAPI responses are translated based on the user's detected locale or the `Accept-Language` header. Over 25 languages are supported.\n\n## Pagination\nEndpoints returning lists support pagination via query parameters.\n\n| Parameter | Type | Optional | Description | Default | Constraints |\n|--------------|---------|----------|-----------------------------------------------------------------------------|---------|--------------------|\n| `page` | Integer | Yes | Page number to retrieve. | 1 | `>= 1` |\n| `limit` | Integer | Yes | Number of results per page. | 25 | `>= 1`, `<= 100` |\n| `pagination` | Boolean | Yes | Opt-in to pagination behavior (required before Nov 1st, 2024 for some endpoints). | false | |\n\n**Pagination Headers:**\n* `X-Page-Count`: Total page count.\n* `X-Page-Current`: Current page number.\n* `X-Page-Size`: Number of items on the current page.\n* `X-Item-Count`: Total number of items across all pages.\n* `Link`: Navigation links (prev, next, first, last).\n\n**Example:**\n```bash\ncurl \"https://api.forwardemail.net/v1/domains?page=2&limit=20&pagination=true\" \\\n -u API_TOKEN:\n```\n\n## Recommended Libraries\n* **Ruby:** [Faraday](https://github.com/lostisland/faraday)\n* **Python:** [requests](https://requests.readthedocs.io/en/latest/)\n* **Java:** [OkHttp](https://square.github.io/okhttp/)\n* **PHP:** [Guzzle](https://docs.guzzlephp.org/en/stable/)\n* **JavaScript/Node.js:** [superagent](https://github.com/visionmedia/superagent) (Maintained by Forward Email)\n* **Go:** `net/http`\n* **.NET:** [RestSharp](https://restsharp.dev/)", "version": "1.0.0", "contact": { "name": "Forward Email Support", "url": "https://forwardemail.net", "email": "api@forwardemail.net" } }, "servers": [ { "url": "https://api.forwardemail.net", "description": "Forward Email API Server" } ], "components": { "securitySchemes": { "ApiKeyAuth": { "type": "http", "scheme": "basic", "description": "\nUse your API Key as the **username** for Basic Authentication. Leave the password field empty.\n\n**Example:**\nIf your API Key is `YOUR_API_KEY`, the Base64 encoded value for the `Authorization` header would be `echo -n \"YOUR_API_KEY:\" | base64`.\n\n```http\nAuthorization: Basic WU9VUl9BUElfS0VZOg==\n```\n" }, "AliasAuth": { "type": "http", "scheme": "basic", "description": "\nUse the generated **alias username and password** for Basic Authentication. This applies to endpoints under:\n* Alias Contacts (CardDAV)\n* Alias Calendars (CalDAV)\n* Alias Messages (IMAP/POP3)\n* Alias Folders (IMAP/POP3)\n* Alias Sieve Scripts\n\n**Example:**\nIf the alias username is `alias@domain.com` and password is `GENERATED_PASSWORD`, the Base64 encoded value would be `echo -n \"alias@domain.com:GENERATED_PASSWORD\" | base64`.\n\n```http\nAuthorization: Basic YWxpYXNAZG9tYWluLmNvbTpHRU5FUkFURURfUEFTU1dPUkQ=\n```\n" } }, "schemas": { "SieveScript": { "type": "object", "required": [ "id", "name", "content", "alias" ], "properties": { "id": { "type": "string", "description": "Unique script identifier" }, "name": { "type": "string", "description": "Script name" }, "content": { "type": "string", "description": "Sieve script content" }, "alias": { "type": "string", "description": "Alias ID this script belongs to" }, "is_active": { "type": "boolean", "description": "Whether the script is active", "default": false }, "priority": { "type": "integer", "description": "Script priority (lower = higher priority)", "default": 0 }, "created_at": { "type": "string", "format": "date-time", "description": "Creation timestamp" }, "updated_at": { "type": "string", "format": "date-time", "description": "Last update timestamp" }, "object": { "type": "string", "example": "sieve_script" } } }, "Error": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string", "description": "Error message" } } }, "Account": { "type": "object", "required": [ "id", "email", "plan", "object" ], "properties": { "sessions": { "type": "array", "items": { "type": "string" } }, "has_newsletter": { "type": "boolean" }, "plan": { "type": "string", "example": "free" }, "email": { "type": "string", "format": "email" }, "max_quota_per_alias": { "type": "integer", "format": "int64" }, "full_email": { "type": "string", "format": "email" }, "display_name": { "type": "string" }, "otp_enabled": { "type": "boolean" }, "last_locale": { "type": "string" }, "address_country": { "type": "string", "nullable": true }, "id": { "type": "string" }, "object": { "type": "string", "example": "user" }, "locale": { "type": "string" }, "preferred_locale": { "type": "string", "description": "User's preferred language setting that overrides automatic detection" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "address_html": { "type": "string" }, "api_token": { "type": "string", "format": "uuid" } }, "example": { "sessions": [], "has_newsletter": true, "plan": "free", "email": "test1@test1.com", "max_quota_per_alias": 10737418240, "full_email": "test1@test1.com", "display_name": "test1@test1.com", "otp_enabled": false, "last_locale": "en", "address_country": "None", "id": "683fb2e81cc5d449a0d4cd9d", "object": "user", "locale": "en", "created_at": "2025-06-04T02:43:52.646Z", "updated_at": "2025-06-04T02:43:55.350Z", "address_html": "", "api_token": "15ac16ae21784aa2cb4d5508" } }, "AliasAccount": { "type": "object", "required": [ "id", "object", "name", "email", "domain_id", "domain_name", "storage_used", "storage_quota" ], "properties": { "id": { "type": "string", "description": "Alias ID" }, "object": { "type": "string", "example": "alias", "description": "Object type" }, "name": { "type": "string", "description": "Alias name (local part of email)" }, "email": { "type": "string", "format": "email", "description": "Full alias email address" }, "domain_id": { "type": "string", "description": "Domain ID" }, "domain_name": { "type": "string", "description": "Domain name" }, "storage_used": { "type": "integer", "format": "int64", "description": "Storage used in bytes for this alias/mailbox" }, "storage_quota": { "type": "integer", "format": "int64", "description": "Storage quota in bytes for this alias/mailbox" }, "has_imap": { "type": "boolean", "description": "Whether IMAP is enabled for this alias" }, "has_pgp": { "type": "boolean", "description": "Whether PGP encryption is enabled" }, "public_key": { "type": "string", "description": "PGP public key if available" }, "has_smime": { "type": "boolean", "description": "Whether S/MIME encryption is enabled" }, "smime_certificate": { "type": "string", "description": "S/MIME X.509 certificate in PEM format" }, "has_wkd_disabled": { "type": "boolean", "description": "Whether WKD (Web Key Directory) public key lookup is disabled for this alias" }, "locale": { "type": "string", "description": "Locale preference" }, "settings": { "type": "object", "description": "Alias settings", "properties": { "mail": { "type": "object", "properties": { "archive_folder": { "type": "string", "nullable": true, "description": "Alias mail archive folder" }, "sent_folder": { "type": "string", "nullable": true, "description": "Alias mail sent folder" }, "drafts_folder": { "type": "string", "nullable": true, "description": "Alias mail drafts folder" } } }, "label_settings": { "type": "object", "description": "Alias label map keyed by keyword", "additionalProperties": { "$ref": "#/components/schemas/SettingsLabelUpdate" } }, "aliases": { "type": "object", "properties": { "defaults": { "type": "object", "description": "Free-form alias defaults such as display_name or signature.", "additionalProperties": true } } } } }, "created_at": { "type": "string", "format": "date-time", "description": "Creation timestamp" }, "updated_at": { "type": "string", "format": "date-time", "description": "Last update timestamp" } }, "example": { "id": "683fb2e81cc5d449a0d4cd9e", "object": "alias", "name": "user", "email": "user@example.com", "domain_id": "683fb2e81cc5d449a0d4cd9f", "domain_name": "example.com", "storage_used": 524288000, "storage_quota": 10737418240, "has_imap": true, "has_pgp": false, "public_key": "", "has_smime": false, "smime_certificate": "", "has_wkd_disabled": false, "locale": "en", "settings": { "mail": { "archive_folder": null, "sent_folder": null, "drafts_folder": null }, "label_settings": {}, "aliases": { "defaults": {} } }, "created_at": "2025-06-04T02:43:52.646Z", "updated_at": "2025-06-04T02:43:55.350Z" } }, "Contact": { "type": "object", "required": [ "id", "uid", "full_name", "content", "etag", "is_group", "emails", "phone_numbers", "created_at", "updated_at", "object" ], "properties": { "id": { "type": "string", "description": "Contact ID (contact_id from CardDAV)" }, "uid": { "type": "string", "description": "Contact UID" }, "full_name": { "type": "string", "description": "Contact's full name" }, "content": { "type": "string", "description": "vCard content" }, "etag": { "type": "string", "description": "ETag for versioning" }, "is_group": { "type": "boolean", "description": "Whether contact is a group" }, "emails": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string", "format": "email" }, "type": { "type": "string", "default": "INTERNET" } }, "required": [ "value" ] }, "description": "Array of email addresses" }, "phone_numbers": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string" }, "type": { "type": "string", "default": "CELL" } }, "required": [ "value" ] }, "description": "Array of phone numbers" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "object": { "type": "string", "enum": [ "contact" ] } }, "example": { "id": "contact123", "uid": "uid123", "full_name": "John Doe", "content": "BEGIN:VCARD\\nVERSION:3.0\\nUID:uid123\\nFN:John Doe\\nEMAIL;TYPE=INTERNET:john@example.com\\nEND:VCARD", "etag": "etag123", "is_group": false, "emails": [ { "value": "john@example.com", "type": "INTERNET" } ], "phone_numbers": [ { "value": "+1234567890", "type": "CELL" } ], "created_at": "2025-01-01T00:00:00.000Z", "updated_at": "2025-01-01T00:00:00.000Z", "object": "contact" } }, "ContactInput": { "type": "object", "properties": { "content": { "type": "string", "description": "vCard content (if not provided, will be generated from other fields)" }, "full_name": { "type": "string", "description": "Contact's full name" }, "contact_id": { "type": "string", "description": "Custom contact ID (if not provided, will be auto-generated)" }, "uid": { "type": "string", "description": "Contact UID (if not provided, will be auto-generated)" }, "emails": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string", "format": "email" }, "type": { "type": "string", "default": "INTERNET" } }, "required": [ "value" ] }, "description": "Array of email addresses" }, "phone_numbers": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string" }, "type": { "type": "string", "default": "CELL" } }, "required": [ "value" ] }, "description": "Array of phone numbers" }, "phones": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string" }, "type": { "type": "string", "default": "CELL" } }, "required": [ "value" ] }, "description": "Array of phone numbers (alias for phone_numbers)" }, "addresses": { "type": "array", "items": { "type": "object", "properties": { "street": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "postalCode": { "type": "string" }, "country": { "type": "string" }, "type": { "type": "string" } } }, "description": "Array of addresses" }, "is_group": { "type": "boolean", "description": "Whether contact is a group" } } }, "ContactUpdateInput": { "type": "object", "properties": { "content": { "type": "string", "description": "vCard content" }, "full_name": { "type": "string", "description": "Contact's full name" }, "emails": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string", "format": "email" }, "type": { "type": "string", "default": "INTERNET" } }, "required": [ "value" ] }, "description": "Array of email addresses" }, "phone_numbers": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string" }, "type": { "type": "string", "default": "CELL" } }, "required": [ "value" ] }, "description": "Array of phone numbers" }, "phones": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string" }, "type": { "type": "string", "default": "CELL" } }, "required": [ "value" ] }, "description": "Array of phone numbers (alias for phone_numbers)" }, "addresses": { "type": "array", "items": { "type": "object", "properties": { "street": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "postalCode": { "type": "string" }, "country": { "type": "string" }, "type": { "type": "string" } } }, "description": "Array of addresses" }, "is_group": { "type": "boolean", "description": "Whether contact is a group" } } }, "Calendar": { "type": "object", "required": [ "id", "name", "description", "color", "timezone", "order", "created_at", "updated_at", "object" ], "properties": { "id": { "type": "string", "description": "Calendar ID (calendarId from CalDAV)" }, "name": { "type": "string", "description": "Calendar name" }, "description": { "type": "string", "description": "Calendar description" }, "color": { "type": "string", "description": "Calendar color (hex format)" }, "timezone": { "type": "string", "description": "Calendar timezone" }, "order": { "type": "integer", "description": "Calendar display order" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "object": { "type": "string", "enum": [ "calendar" ] } }, "example": { "id": "calendar123", "name": "Personal Calendar", "description": "My personal calendar", "color": "#ff0000", "timezone": "America/New_York", "order": 0, "created_at": "2025-01-01T00:00:00.000Z", "updated_at": "2025-01-01T00:00:00.000Z", "object": "calendar" } }, "CalendarInput": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "description": "Calendar name" }, "calendar_id": { "type": "string", "description": "Custom calendar ID (if not provided, will be auto-generated)" }, "description": { "type": "string", "description": "Calendar description" }, "color": { "type": "string", "description": "Calendar color (hex format, if not provided, will be auto-generated)" }, "timezone": { "type": "string", "description": "Calendar timezone (defaults to user's timezone or UTC)" }, "order": { "type": "integer", "description": "Calendar display order (defaults to 0)" } } }, "CalendarUpdateInput": { "type": "object", "properties": { "name": { "type": "string", "description": "Calendar name" }, "description": { "type": "string", "description": "Calendar description" }, "color": { "type": "string", "description": "Calendar color (hex format)" }, "timezone": { "type": "string", "description": "Calendar timezone" }, "order": { "type": "integer", "description": "Calendar display order" } } }, "CalendarEvent": { "type": "object", "required": [ "id", "calendar_id", "ical", "created_at", "updated_at", "object" ], "properties": { "id": { "type": "string", "description": "Calendar event ID (eventId from CalDAV)" }, "calendar_id": { "type": "string", "description": "ID of the calendar this event belongs to" }, "ical": { "type": "string", "description": "iCalendar (RFC 5545) data for the event" }, "summary": { "type": "string", "description": "Event title/summary (extracted from iCal data)" }, "description": { "type": "string", "description": "Event description (extracted from iCal data)" }, "location": { "type": "string", "description": "Event location (extracted from iCal data)" }, "start_date": { "type": "string", "format": "date-time", "description": "Event start date/time (extracted from iCal data)" }, "end_date": { "type": "string", "format": "date-time", "description": "Event end date/time (extracted from iCal data)" }, "uid": { "type": "string", "description": "Unique identifier from iCal data" }, "status": { "type": "string", "description": "Event status (extracted from iCal data)" }, "organizer": { "type": "string", "description": "Event organizer (extracted from iCal data)" }, "deleted_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Soft deletion timestamp" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "object": { "type": "string", "enum": [ "calendar_event" ] } }, "example": { "id": "event123", "calendar_id": "calendar123", "ical": "BEGIN:VCALENDAR\nVERSION:2.0\nPRODID:-//Example Corp//Example Calendar//EN\nBEGIN:VEVENT\nUID:event123@example.com\nDTSTART:20250101T120000Z\nDTEND:20250101T130000Z\nSUMMARY:Example Event\nDESCRIPTION:This is an example event\nLOCATION:Conference Room A\nSTATUS:CONFIRMED\nEND:VEVENT\nEND:VCALENDAR", "summary": "Example Event", "description": "This is an example event", "location": "Conference Room A", "start_date": "2025-01-01T12:00:00.000Z", "end_date": "2025-01-01T13:00:00.000Z", "uid": "event123@example.com", "status": "CONFIRMED", "organizer": null, "deleted_at": null, "created_at": "2025-01-01T00:00:00.000Z", "updated_at": "2025-01-01T00:00:00.000Z", "object": "calendar_event" } }, "CalendarEventInput": { "type": "object", "required": [ "calendar_id", "ical" ], "properties": { "calendar_id": { "type": "string", "description": "ID of the calendar to add the event to" }, "event_id": { "type": "string", "description": "Custom event ID (if not provided, will be auto-generated)" }, "ical": { "type": "string", "description": "iCalendar (RFC 5545) data for the event. Must be valid iCal format." } }, "example": { "calendar_id": "calendar123", "ical": "BEGIN:VCALENDAR\nVERSION:2.0\nPRODID:-//Example Corp//Example Calendar//EN\nBEGIN:VEVENT\nUID:event123@example.com\nDTSTART:20250101T120000Z\nDTEND:20250101T130000Z\nSUMMARY:Example Event\nDESCRIPTION:This is an example event\nLOCATION:Conference Room A\nSTATUS:CONFIRMED\nEND:VEVENT\nEND:VCALENDAR" } }, "CalendarEventUpdateInput": { "type": "object", "properties": { "calendar_id": { "type": "string", "description": "Move event to a different calendar" }, "ical": { "type": "string", "description": "Updated iCalendar (RFC 5545) data for the event" } } }, "Folder": { "type": "object", "required": [ "id", "path", "name", "parent", "uid_validity", "uid_next", "modify_index", "subscribed", "flags", "retention", "special_use", "created_at", "updated_at", "object" ], "properties": { "id": { "type": "string", "description": "Folder ID" }, "path": { "type": "string", "description": "Full folder path" }, "name": { "type": "string", "description": "Folder name (last part of path)" }, "parent": { "type": "string", "nullable": true, "description": "Parent folder path" }, "uid_validity": { "type": "integer", "description": "IMAP UID validity" }, "uid_next": { "type": "integer", "description": "Next UID value" }, "modify_index": { "type": "integer", "description": "Modification index" }, "subscribed": { "type": "boolean", "description": "Whether folder is subscribed" }, "flags": { "type": "array", "items": { "type": "string" }, "description": "Folder flags" }, "retention": { "type": "integer", "nullable": true, "description": "Message retention period" }, "special_use": { "type": "string", "nullable": true, "description": "Special use designation" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "object": { "type": "string", "enum": [ "folder" ] } }, "example": { "id": "folder123", "path": "INBOX/Subfolder", "name": "Subfolder", "parent": "INBOX", "uid_validity": 123456, "uid_next": 1, "modify_index": 1, "subscribed": true, "flags": [], "retention": null, "special_use": null, "created_at": "2025-01-01T00:00:00.000Z", "updated_at": "2025-01-01T00:00:00.000Z", "object": "folder" } }, "FolderInput": { "type": "object", "required": [ "path" ], "properties": { "path": { "type": "string", "description": "Folder path/name" } } }, "FolderUpdateInput": { "type": "object", "required": [ "path" ], "properties": { "path": { "type": "string", "description": "New folder path/name" } } }, "Message": { "type": "object", "required": [ "id", "root_id", "folder_id", "folder_path", "thread_id", "header_message_id", "is_unread", "is_flagged", "is_deleted", "is_draft", "is_junk", "is_copied", "is_encrypted", "is_searchable", "is_expired", "has_attachment", "retention_date", "internal_date", "header_date", "subject", "flags", "labels", "size", "uid", "modseq", "transaction", "remote_address", "created_at", "updated_at", "object" ], "properties": { "id": { "type": "string", "description": "Message ID" }, "root_id": { "type": "string", "description": "Root message ID for threading" }, "folder_id": { "type": "string", "description": "Folder ID containing the message" }, "folder_path": { "type": "string", "description": "Folder path containing the message" }, "thread_id": { "type": "string", "description": "Thread ID for conversation grouping" }, "header_message_id": { "type": "string", "description": "Message-ID header value" }, "is_unread": { "type": "boolean", "description": "Whether message is unread" }, "is_flagged": { "type": "boolean", "description": "Whether message is flagged" }, "is_deleted": { "type": "boolean", "description": "Whether message is deleted" }, "is_draft": { "type": "boolean", "description": "Whether message is a draft" }, "is_junk": { "type": "boolean", "description": "Whether message is junk/spam" }, "is_copied": { "type": "boolean", "description": "Whether message is copied" }, "is_encrypted": { "type": "boolean", "description": "Whether message is encrypted (PGP/MIME or S/MIME)" }, "is_searchable": { "type": "boolean", "description": "Whether message is searchable" }, "is_expired": { "type": "boolean", "description": "Whether message is expired" }, "has_attachment": { "type": "boolean", "description": "Whether message has attachments" }, "retention_date": { "type": "string", "format": "date-time", "nullable": true, "description": "Message retention date" }, "internal_date": { "type": "string", "format": "date-time", "description": "Internal date (IMAP)" }, "header_date": { "type": "string", "format": "date-time", "description": "Date from message headers" }, "subject": { "type": "string", "description": "Message subject" }, "flags": { "type": "array", "items": { "type": "string" }, "description": "IMAP flags" }, "labels": { "type": "array", "items": { "type": "string" }, "description": "User-defined labels (lowercase, max 10)", "example": [ "work", "important", "follow-up" ] }, "size": { "type": "integer", "description": "Message size in bytes" }, "uid": { "type": "integer", "description": "IMAP UID" }, "modseq": { "type": "integer", "description": "Modification sequence" }, "transaction": { "type": "string", "description": "Transaction type" }, "remote_address": { "type": "string", "description": "Remote IP address" }, "created_at": { "type": "string", "format": "date-time", "description": "Message creation timestamp" }, "updated_at": { "type": "string", "format": "date-time", "description": "Message last update timestamp" }, "nodemailer": { "type": "object", "description": "Parsed message object (included by default, set ?nodemailer=false to exclude)" }, "raw": { "type": "string", "description": "Raw message content (included by default, set ?raw=false to exclude)" }, "object": { "type": "string", "enum": [ "message" ] } }, "example": { "id": "message123", "root_id": "root123", "folder_id": "folder123", "folder_path": "INBOX", "thread_id": "thread123", "header_message_id": "", "is_unread": true, "is_flagged": false, "is_deleted": false, "is_draft": false, "is_junk": false, "is_copied": false, "is_encrypted": false, "is_searchable": true, "is_expired": false, "has_attachment": false, "retention_date": null, "internal_date": "2025-01-01T00:00:00.000Z", "header_date": "2025-01-01T00:00:00.000Z", "subject": "Test Message", "flags": [ "\\Seen" ], "size": 1024, "uid": 1, "modseq": 1, "transaction": "API", "remote_address": "127.0.0.1", "created_at": "2025-01-01T00:00:00.000Z", "updated_at": "2025-01-01T00:00:00.000Z", "object": "message" } }, "MessageInput": { "type": "object", "properties": { "from": { "type": "string", "format": "email", "description": "Sender email address" }, "to": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string", "format": "email" } } ], "description": "Recipient email addresses" }, "cc": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string", "format": "email" } } ], "description": "CC recipient email addresses" }, "bcc": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string", "format": "email" } } ], "description": "BCC recipient email addresses" }, "subject": { "type": "string", "description": "Message subject" }, "text": { "type": "string", "description": "Plain text content" }, "html": { "type": "string", "description": "HTML content" }, "attachments": { "type": "array", "items": { "type": "object" }, "description": "Message attachments (Nodemailer format)" }, "folder": { "type": "string", "description": "Target folder (defaults to INBOX)" }, "flags": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ], "description": "IMAP flags to set on the message" }, "labels": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ], "description": "User-defined labels to set on the message. Can be a single label string or an array of labels. Labels must start with a letter, digit, backslash, or dollar sign, and can contain word characters, dots, and hyphens. Maximum of 10 labels per message. Labels are case-insensitive and will be stored in lowercase.", "example": [ "work", "important" ] } } }, "MessageUpdateInput": { "type": "object", "properties": { "flags": { "type": "array", "items": { "type": "string" }, "description": "IMAP flags to set on the message" }, "labels": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ], "description": "User-defined labels to set on the message. Can be a single label string or an array of labels. Labels must start with a letter, digit, backslash, or dollar sign, and can contain word characters, dots, and hyphens. Maximum of 10 labels per message. Labels are case-insensitive and will be stored in lowercase.", "example": [ "work", "important" ] }, "folder": { "type": "string", "description": "Move message to this folder" } } }, "Email": { "type": "object", "required": [ "id", "object", "status", "alias", "domain", "user" ], "properties": { "is_redacted": { "type": "boolean" }, "hard_bounces": { "type": "array", "items": { "type": "string" } }, "soft_bounces": { "type": "array", "items": { "type": "string" } }, "is_bounce": { "type": "boolean" }, "alias": { "type": "string" }, "domain": { "type": "string" }, "user": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "queued", "sent", "partially_sent", "deferred", "bounced", "rejected" ], "description": "The current status of the email. Scheduling is determined by the `date` field.", "example": "sent" }, "is_locked": { "type": "boolean" }, "envelope": { "type": "object", "properties": { "from": { "type": "string", "format": "email" }, "to": { "type": "array", "items": { "type": "string", "format": "email" } } } }, "messageId": { "type": "string" }, "date": { "type": "string", "format": "date-time", "description": "The email's Date header. If set to a future time (more than 1 minute ahead), the email will be held until that time. Maximum 30 days in the future from creation." }, "subject": { "type": "string" }, "accepted": { "type": "array", "items": { "type": "string", "format": "email" } }, "id": { "type": "string" }, "object": { "type": "string", "example": "email" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "link": { "type": "string", "format": "uri" }, "requireTLS": { "type": "boolean", "description": "Indicates if TLS is required for the entire delivery chain (RFC 8689)." } }, "example": { "is_redacted": true, "hard_bounces": [], "soft_bounces": [], "is_bounce": false, "alias": "67a180fxxxxxxxe46a3f0edf", "domain": "5efae85dxxxxxxxf4bb53c7a", "user": "5efabd3907xxxxxxx12890b8", "status": "sent", "is_locked": false, "envelope": { "from": "test@test.com", "to": [ "test@test1.com" ] }, "messageId": "1a04fee3-5230-4a85-9111-a2c376835885@forwardemail.net", "date": "2025-06-04T03:32:19.000Z", "subject": "testing", "accepted": [ "test@test1.com" ], "id": "683fbe4d5baef1b583a1xxxx", "object": "email", "created_at": "2025-06-04T03:32:29.138Z", "updated_at": "2025-06-04T03:32:33.847Z", "link": "https://forwardemail.net/my-account/emails/683fbe4d5baef1b583a11e54" } }, "EmailList": { "type": "array", "items": { "$ref": "#/components/schemas/Email" } }, "SMTP": { "type": "object", "properties": { "from": { "type": "string", "format": "email", "description": "The email address of the sender (must exist as an alias of the domain)." }, "to": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string", "format": "email" } } ], "description": "Comma-separated list or an array of recipients for the 'To' header." }, "cc": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string", "format": "email" } } ], "description": "Comma-separated list or an array of recipients for the 'Cc' header." }, "bcc": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string", "format": "email" } } ], "description": "Comma-separated list or an array of recipients for the 'Bcc' header." }, "subject": { "type": "string", "description": "The subject of the email." }, "text": { "type": "string", "description": "The plaintext version of the message." }, "html": { "type": "string", "description": "The HTML version of the message." }, "attachments": { "type": "array", "items": { "type": "object" }, "description": "An array of attachment objects (see Nodemailer's common fields)." }, "sender": { "type": "string", "format": "email", "description": "The email address for the 'Sender' header." }, "replyTo": { "type": "string", "format": "email", "description": "The email address for the 'Reply-To' header." }, "inReplyTo": { "type": "string", "description": "The Message-ID the message is in reply to." }, "references": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ], "description": "Space-separated list or an array of Message-IDs." }, "attachDataUrls": { "type": "boolean", "description": "If true, converts data: images in the HTML content to embedded attachments." }, "watchHtml": { "type": "string", "description": "Apple Watch specific HTML version of the message." }, "amp": { "type": "string", "description": "AMP4EMAIL specific HTML version of the message." }, "icalEvent": { "type": "object", "description": "An iCalendar event as an alternative message content." }, "alternatives": { "type": "array", "items": { "type": "object" }, "description": "An array of alternative message content." }, "encoding": { "type": "string", "description": "Encoding for the text and HTML strings (e.g., 'utf-8', 'hex', 'base64')." }, "raw": { "type": "string", "description": "Custom generated RFC822 formatted message (instead of using Nodemailer generation)." }, "textEncoding": { "type": "string", "enum": [ "quoted-printable", "base64" ], "description": "Encoding forced to be used for text values." }, "priority": { "type": "string", "enum": [ "high", "normal", "low" ], "description": "Priority level for the email." }, "headers": { "oneOf": [ { "type": "object", "additionalProperties": true }, { "type": "array", "items": { "type": "object" } } ], "description": "Object or array of additional header fields." }, "messageId": { "type": "string", "description": "Optional Message-ID for the 'Message-ID' header." }, "date": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "string" } ], "description": "Optional Date header. If set to a future time (more than 1 minute ahead), the email will be held until that time. Cannot be more than 30 days in the future from creation.", "example": "2025-06-04T15:30:00.000Z" }, "list": { "type": "object", "description": "Optional object of List-* headers." }, "requireTLS": { "type": "boolean", "description": "If true, requires TLS for the entire delivery chain (RFC 8689). The message will only be transmitted over TLS-encrypted connections." } } }, "Domain": { "type": "object", "properties": { "has_newsletter": { "type": "boolean" }, "ignore_mx_check": { "type": "boolean" }, "allow_subdomain_forwarding": { "description": "Allow wildcard subdomain forwarding. When enabled on a paid plan (Enhanced Protection or Team), any subdomain that has no DNS records of its own inherits the forwarding configuration published at this domain’s root (apex). Verified ownership is required: the apex must publish a forward-email-site-verification record matching this domain. This setting does not apply to the free plan.", "type": "boolean" }, "has_delivery_logs": { "type": "boolean" }, "retention_days": { "type": "integer" }, "has_regex": { "type": "boolean" }, "has_catchall": { "type": "boolean" }, "allowlist": { "type": "array", "items": { "type": "string" } }, "denylist": { "type": "array", "items": { "type": "string" } }, "restricted_alias_names": { "type": "array", "items": { "type": "string" } }, "has_adult_content_protection": { "type": "boolean" }, "has_phishing_protection": { "type": "boolean" }, "has_executable_protection": { "type": "boolean" }, "has_virus_protection": { "type": "boolean" }, "is_catchall_regex_disabled": { "type": "boolean" }, "has_smtp": { "type": "boolean" }, "is_smtp_suspended": { "type": "boolean" }, "plan": { "type": "string" }, "max_recipients_per_alias": { "type": "integer" }, "alias_default_smtp_limit": { "type": "integer", "description": "Default daily SMTP sending limit applied to newly created aliases on this domain. Set to 0 to disable (aliases will use the domain-wide limit). Cannot exceed the domain's effective SMTP limit.", "minimum": 0, "default": 0 }, "smtp_port": { "type": "string" }, "name": { "type": "string" }, "has_mx_record": { "type": "boolean" }, "has_txt_record": { "type": "boolean" }, "has_dkim_record": { "type": "boolean" }, "has_return_path_record": { "type": "boolean" }, "has_dmarc_record": { "type": "boolean" }, "has_recipient_verification": { "type": "boolean" }, "has_custom_verification": { "type": "boolean" }, "has_custom_s3": { "type": "boolean", "description": "Whether this domain uses custom S3-compatible storage for backups" }, "s3_endpoint": { "type": "string", "description": "Custom S3-compatible endpoint URL (e.g. https://s3.us-east-1.amazonaws.com, https://.r2.cloudflarestorage.com)" }, "s3_region": { "type": "string", "description": "S3 region (e.g. us-east-1, auto). Defaults to auto if not specified." }, "s3_bucket": { "type": "string", "description": "S3 bucket name for storing backups. The bucket must already exist." }, "require_tls_inbound": { "type": "boolean", "description": "When enabled, reject inbound emails not sent over TLS" }, "verification_record": { "type": "string" }, "id": { "type": "string" }, "object": { "type": "string", "enum": [ "domain" ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "storage_used": { "type": "integer" }, "storage_used_by_aliases": { "type": "integer" }, "storage_quota": { "type": "integer" }, "smtp_dns_records": { "type": "object", "properties": { "dkim": { "type": "object", "properties": { "name": { "type": "string" }, "value": { "type": "string" } } }, "return_path": { "type": "object", "properties": { "name": { "type": "string" }, "value": { "type": "string" } } }, "dmarc": { "type": "object", "properties": { "name": { "type": "string" }, "value": { "type": "string" } } } } }, "link": { "type": "string", "format": "uri" } }, "example": [ { "has_newsletter": false, "ignore_mx_check": false, "allow_subdomain_forwarding": false, "has_delivery_logs": false, "retention_days": 0, "has_regex": false, "has_catchall": true, "allowlist": [], "denylist": [], "restricted_alias_names": [], "has_adult_content_protection": true, "has_phishing_protection": true, "has_executable_protection": true, "has_virus_protection": true, "is_catchall_regex_disabled": false, "has_smtp": false, "is_smtp_suspended": false, "plan": "team", "max_recipients_per_alias": 10, "alias_default_smtp_limit": 0, "smtp_port": "25", "name": "test.com", "has_mx_record": false, "has_txt_record": false, "has_dkim_record": false, "has_return_path_record": false, "has_dmarc_record": false, "has_recipient_verification": false, "has_custom_verification": false, "verification_record": "kcjg6vrO8Q", "id": "683f1172c4bad2524410b857", "object": "domain", "created_at": "2025-06-03T15:14:59.000Z", "updated_at": "2025-06-03T15:14:59.254Z", "storage_used": 0, "storage_used_by_aliases": 0, "storage_quota": 10737418240, "smtp_dns_records": { "dkim": { "name": "fe-ebf3212716._domainkey", "value": "v=DKIM1; k=rsa; p=MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQCcG+YBDPhyH8bLmyflmU9w1klYDeWpEufIlVqyWqly9lC+J/ntkKn4gum28EeE6vR+55x4JFCR8qSaw0YO1eCRwBgpFB0kKzbELHh2i2TKKwrqB3gPLXp4q4lbcGX2eD6fPCRwckTHqmiOzMhX8GD60zVlEvabok4LJ1i/BOyh6wIDAQAB;" }, "return_path": { "name": "fe-bounces", "value": "forwardemail.net" }, "dmarc": { "name": "_dmarc", "value": "v=DMARC1; p=reject; pct=100; rua=mailto:dmarc-683f1172c4bad2524410b857@localhost;" } }, "link": "http://localhost:3000/my-account/domains/test.com" } ] }, "CreateDomainInput": { "type": "object", "required": [ "domain" ], "properties": { "domain": { "type": "string", "description": "Fully qualified domain name (FQDN) or IP address" }, "team_domain": { "type": "string", "nullable": true, "description": "Assign to same team from another domain; can be a domain ID or FQDN. Use \"none\" to explicitly disable." }, "plan": { "type": "string", "enum": [ "free", "enhanced_protection", "team" ], "description": "Plan type (defaults to 'free' or the user's current paid plan)" }, "catchall": { "oneOf": [ { "type": "boolean" }, { "type": "string", "description": "Delimited list of email addresses (comma, space, or newline separated)" } ], "description": "Create a default catch-all alias (defaults to true)" }, "has_adult_content_protection": { "type": "boolean", "description": "Enable Spam Scanner adult content protection" }, "has_phishing_protection": { "type": "boolean", "description": "Enable Spam Scanner phishing protection" }, "has_executable_protection": { "type": "boolean", "description": "Enable Spam Scanner executable protection" }, "has_virus_protection": { "type": "boolean", "description": "Enable Spam Scanner virus protection" }, "has_recipient_verification": { "type": "boolean", "description": "Require alias recipients to click email verification link" }, "ignore_mx_check": { "type": "boolean", "description": "Ignore MX record check for advanced mail routing setups" }, "allow_subdomain_forwarding": { "description": "Allow wildcard subdomain forwarding. When enabled on a paid plan (Enhanced Protection or Team), any subdomain that has no DNS records of its own inherits the forwarding configuration published at this domain’s root (apex). Verified ownership is required: the apex must publish a forward-email-site-verification record matching this domain. This setting does not apply to the free plan.", "type": "boolean" }, "has_delivery_logs": { "type": "boolean", "description": "Opt-in to store headers and metadata (excluding message content) for successfully forwarded, webhook-sent, outbound SMTP, and IMAP-delivered emails, with logs retained for 7 days. This feature helps you monitor and troubleshoot email delivery performance with detailed insights into successful transmissions." }, "retention_days": { "type": "integer", "minimum": 0, "maximum": 30, "description": "Number of days to retain outbound SMTP logs (0–30, default: 0)" }, "bounce_webhook": { "oneOf": [ { "type": "string", "format": "uri", "description": "Webhook URL to receive bounce events" }, { "type": "boolean", "enum": [ false ], "description": "Disable bounce webhook" } ] }, "max_quota_per_alias": { "type": "string", "description": "Storage max quota per alias (e.g. '1 GB')" } } }, "UpdateDomainInput": { "type": "object", "properties": { "smtp_port": { "oneOf": [ { "type": "string" }, { "type": "number" } ], "description": "Custom port to configure for SMTP forwarding (default is '25')" }, "has_adult_content_protection": { "type": "boolean", "description": "Whether to enable Spam Scanner adult content protection on this domain" }, "has_phishing_protection": { "type": "boolean", "description": "Whether to enable Spam Scanner phishing protection on this domain" }, "has_executable_protection": { "type": "boolean", "description": "Whether to enable Spam Scanner executable protection on this domain" }, "has_virus_protection": { "type": "boolean", "description": "Whether to enable Spam Scanner virus protection on this domain" }, "has_recipient_verification": { "type": "boolean", "description": "Global domain default for whether to require alias recipients to click an email verification link for emails to flow through" }, "ignore_mx_check": { "type": "boolean", "description": "Whether to ignore the MX record check on the domain for verification (mainly for advanced MX routing setups)" }, "allow_subdomain_forwarding": { "description": "Allow wildcard subdomain forwarding. When enabled on a paid plan (Enhanced Protection or Team), any subdomain that has no DNS records of its own inherits the forwarding configuration published at this domain’s root (apex). Verified ownership is required: the apex must publish a forward-email-site-verification record matching this domain. This setting does not apply to the free plan.", "type": "boolean" }, "has_delivery_logs": { "type": "boolean", "description": "Opt-in to store headers and metadata (excluding message content) for successfully forwarded, webhook-sent, outbound SMTP, and IMAP-delivered emails, with logs retained for 7 days. This feature helps you monitor and troubleshoot email delivery performance with detailed insights into successful transmissions." }, "retention_days": { "type": "integer", "minimum": 0, "maximum": 30, "description": "Number of days to store outbound SMTP emails (0 = purge immediately)" }, "bounce_webhook": { "oneOf": [ { "type": "string", "format": "uri" }, { "type": "boolean", "enum": [ false ] } ], "description": "Webhook URL to receive bounce notifications, or false to disable" }, "max_quota_per_alias": { "type": "string", "description": "Storage quota per alias (e.g. '1 GB', parsed into bytes)" }, "has_custom_s3": { "type": "boolean", "description": "Whether to enable custom S3-compatible storage for IMAP/SQLite backups on this domain" }, "s3_endpoint": { "type": "string", "format": "uri", "description": "Custom S3-compatible endpoint URL (e.g. https://s3.us-east-1.amazonaws.com)" }, "s3_access_key_id": { "type": "string", "description": "S3 access key ID. Encrypted at rest. Leave blank when updating to keep existing value." }, "s3_secret_access_key": { "type": "string", "description": "S3 secret access key. Encrypted at rest. Leave blank when updating to keep existing value." }, "s3_region": { "type": "string", "description": "S3 region (e.g. us-east-1, auto). Defaults to auto." }, "s3_bucket": { "type": "string", "description": "S3 bucket name for storing backups. The bucket must already exist and must not be publicly accessible." }, "allowlist": { "type": "array", "items": { "type": "string" }, "description": "List of allowlisted senders (IP addresses, fully qualified domain names, email addresses, or wildcard TLDs). When set, only mail from these senders will be accepted. Replaces the existing list. Wildcard public-suffix rules may contain multiple labels, for example `*.gov.co` and `*.gov.br`; they match senders under that exact suffix." }, "denylist": { "type": "array", "items": { "type": "string" }, "description": "List of denylisted senders (IP addresses, fully qualified domain names, email addresses, or wildcard TLDs). Mail from these senders will be rejected. Replaces the existing list. Wildcard public-suffix rules may contain multiple labels, for example `*.gov.co` and `*.gov.br`; they match senders under that exact suffix." } } }, "Alias": { "type": "object", "properties": { "user": { "type": "object", "properties": { "email": { "type": "string", "format": "email" }, "display_name": { "type": "string" }, "id": { "type": "string" } }, "required": [ "email", "display_name", "id" ] }, "domain": { "type": "object", "properties": { "name": { "type": "string" }, "id": { "type": "string" } }, "required": [ "name", "id" ] }, "name": { "type": "string" }, "labels": { "type": "array", "items": { "type": "string" } }, "is_enabled": { "type": "boolean" }, "has_recipient_verification": { "type": "boolean" }, "verified_recipients": { "type": "array", "items": { "type": "string", "format": "email" } }, "pending_recipients": { "type": "array", "items": { "type": "string", "format": "email" } }, "recipients": { "type": "array", "items": { "type": "string", "format": "email" } }, "id": { "type": "string" }, "object": { "type": "string", "enum": [ "alias" ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "storage_location": { "type": "string" }, "has_imap": { "type": "boolean" }, "retention": { "type": "integer", "minimum": 0, "maximum": 365, "description": "Retention period in days (0-365) for Trash and Junk mailbox cleanup. 0 means automatic storage-based scaling." }, "smtp_limit": { "type": "integer", "minimum": 0, "default": 0, "description": "Per-alias daily SMTP outbound message limit. Set to 0 to use the domain-level limit." }, "is_smtp_suspended": { "type": "boolean", "default": false, "description": "Whether this alias is currently suspended from outbound SMTP access.", "readOnly": true }, "smtp_suspended_sent_at": { "type": "string", "format": "date-time", "description": "The date and time when the alias was suspended from outbound SMTP.", "readOnly": true, "nullable": true } }, "required": [ "user", "domain", "name", "labels", "is_enabled", "has_recipient_verification", "verified_recipients", "pending_recipients", "recipients", "id", "object", "created_at", "updated_at", "storage_location", "has_imap", "retention" ], "example": { "user": { "email": "test@test.com", "display_name": "test@test.com", "id": "5efabd39xxxxxxx4512890b8" }, "domain": { "name": "mailsire.com", "id": "5e3c0550xxxxxxx09b7ba023" }, "name": "abc123", "labels": [], "is_enabled": true, "has_recipient_verification": false, "verified_recipients": [], "pending_recipients": [], "recipients": [ "abc@test1.com" ], "id": "62fa3dcxxxxxxx79dda83ff2", "object": "alias", "created_at": "2022-08-15T12:36:26.593Z", "updated_at": "2022-08-15T12:36:26.593Z", "storage_location": "storage_loc", "has_imap": false, "retention": 0 } }, "AliasInput": { "type": "object", "properties": { "name": { "type": "string", "description": "Alias name (if not provided or if blank, then a random alias is generated)" }, "recipients": { "oneOf": [ { "type": "string", "description": "Line-break/space/comma separated string of valid email addresses, FQDNs, IPs, or webhook URLs" }, { "type": "array", "items": { "type": "string", "format": "email" }, "description": "Array of valid recipients" } ], "description": "List of recipients. If not provided or empty, defaults to the requester's email" }, "description": { "type": "string", "description": "Alias description" }, "labels": { "oneOf": [ { "type": "string", "description": "Line-break/space/comma separated string of labels" }, { "type": "array", "items": { "type": "string" }, "description": "Array of labels" } ] }, "has_recipient_verification": { "type": "boolean", "description": "Require recipients to click verification link (defaults to domain setting)" }, "is_enabled": { "type": "boolean", "description": "Whether to enable or disable this alias" }, "error_code_if_disabled": { "type": "number", "enum": [ 250, 421, 550 ], "description": "Error code if alias is disabled. Defaults to 250" }, "has_imap": { "type": "boolean", "description": "Enable or disable IMAP storage for this alias" }, "has_pgp": { "type": "boolean", "description": "Enable or disable OpenPGP encryption for this alias" }, "public_key": { "type": "string", "description": "OpenPGP public key in ASCII Armor format" }, "has_smime": { "type": "boolean", "description": "Enable or disable S/MIME encryption for this alias" }, "smime_certificate": { "type": "string", "description": "S/MIME X.509 certificate in PEM format" }, "has_wkd_disabled": { "type": "boolean", "description": "Whether WKD (Web Key Directory) public key lookup is disabled for this alias" }, "max_quota": { "type": "string", "description": "Storage max quota (e.g. '1 GB')" }, "vacation_responder_is_enabled": { "type": "boolean", "description": "Enable or disable vacation responder" }, "vacation_responder_start_date": { "type": "string", "description": "Start date (e.g. 'YYYY-MM-DD') for vacation responder" }, "vacation_responder_end_date": { "type": "string", "description": "End date (e.g. 'YYYY-MM-DD') for vacation responder" }, "vacation_responder_subject": { "type": "string", "description": "Plaintext subject for vacation responder" }, "vacation_responder_message": { "type": "string", "description": "Plaintext message for vacation responder" }, "retention": { "type": "integer", "minimum": 0, "maximum": 365, "description": "Retention period in days (0-365) for Trash and Junk mailbox cleanup. Set to 0 to use automatic storage-based scaling." }, "smtp_limit": { "type": "integer", "minimum": 0, "default": 0, "description": "Per-alias daily SMTP outbound message limit. Set to 0 to use the domain-level limit." } } }, "AliasUpdateInput": { "type": "object", "properties": { "name": { "type": "string", "description": "Alias name" }, "recipients": { "oneOf": [ { "type": "string", "description": "Line-break/space/comma separated string of valid email addresses, FQDNs, IPs, or webhook URLs" }, { "type": "array", "items": { "type": "string", "format": "email" }, "description": "Array of valid recipients. Pass an empty array to remove all forwarding recipients (e.g. for IMAP-only aliases)." } ], "description": "If omitted, existing recipients are preserved. Pass an empty array to clear all forwarding recipients." }, "description": { "type": "string", "description": "Alias description" }, "labels": { "oneOf": [ { "type": "string", "description": "Line-break/space/comma separated string of labels" }, { "type": "array", "items": { "type": "string" }, "description": "Array of labels" } ] }, "has_recipient_verification": { "type": "boolean", "description": "Require recipients to click verification link (defaults to domain setting)" }, "is_enabled": { "type": "boolean", "description": "Enable or disable alias" }, "error_code_if_disabled": { "type": "number", "enum": [ 250, 421, 550 ], "description": "Error code to use if alias is disabled (defaults to 250)" }, "has_imap": { "type": "boolean", "description": "Enable or disable IMAP storage" }, "has_pgp": { "type": "boolean", "description": "Enable or disable OpenPGP encryption" }, "public_key": { "type": "string", "description": "OpenPGP public key in ASCII Armor format" }, "has_smime": { "type": "boolean", "description": "Enable or disable S/MIME encryption" }, "smime_certificate": { "type": "string", "description": "S/MIME X.509 certificate in PEM format" }, "has_wkd_disabled": { "type": "boolean", "description": "Whether WKD (Web Key Directory) public key lookup is disabled for this alias" }, "max_quota": { "type": "string", "description": "Storage maximum quota (e.g., '1 GB')" }, "vacation_responder_is_enabled": { "type": "boolean", "description": "Enable or disable vacation responder" }, "vacation_responder_start_date": { "type": "string", "description": "Vacation responder start date (e.g. YYYY-MM-DD)" }, "vacation_responder_end_date": { "type": "string", "description": "Vacation responder end date (e.g. YYYY-MM-DD)" }, "vacation_responder_subject": { "type": "string", "description": "Plaintext subject of vacation responder" }, "vacation_responder_message": { "type": "string", "description": "Plaintext message of vacation responder" }, "retention": { "type": "integer", "minimum": 0, "maximum": 365, "description": "Retention period in days (0-365) for Trash and Junk mailbox cleanup. Set to 0 to use automatic storage-based scaling." }, "smtp_limit": { "type": "integer", "minimum": 0, "default": 0, "description": "Per-alias daily SMTP outbound message limit. Set to 0 to use the domain-level limit." } } }, "GenerateAliasPasswordInput": { "type": "object", "properties": { "new_password": { "type": "string", "description": "Your custom new password to use for the alias. Custom mailbox passwords must be 128 characters or fewer, cannot start or end with whitespace, and cannot contain quotes or apostrophes." }, "password": { "type": "string", "description": "Existing password for alias to change it without deleting mailbox storage" }, "is_override": { "type": "boolean", "description": "Override existing password and delete IMAP storage (use with caution)" }, "emailed_instructions": { "type": "string", "format": "email", "description": "Email address to send alias password and setup instructions" } } }, "EmailLimit": { "type": "object", "properties": { "count": { "type": "integer", "description": "Current count of emails sent" }, "limit": { "type": "integer", "description": "Maximum number of emails allowed" } } }, "SavedSearch": { "type": "object", "description": "Saved search definition stored per alias.", "properties": { "name": { "type": "string", "maxLength": 100, "description": "Display name for the saved search" }, "query": { "type": "string", "maxLength": 500, "description": "Search query string to reuse (e.g., \"from:billing\")" } }, "required": [ "name", "query" ] }, "ShortcutMap": { "type": "object", "description": "Map of actions to keybindings for keyboard shortcuts.", "additionalProperties": { "type": "string", "description": "Keybinding for the action (e.g., \"e\" for archive)" } }, "SettingsLabelUpdate": { "type": "object", "description": "Fields allowed when updating a label definition.", "properties": { "name": { "type": "string", "description": "Human-readable label name shown in the UI" }, "color": { "type": "string", "pattern": "^#([A-Fa-f0-9]{6}|[A-Fa-f0-9]{8})$", "description": "Hex color used for UI rendering" }, "hidden": { "type": "boolean", "description": "Hide the label in the UI while preserving the keyword" }, "source": { "type": "string", "description": "Label origin for filtering and migrations", "enum": [ "custom", "system", "imported" ] } } }, "Member": { "type": "object", "properties": { "id": { "type": "string", "description": "Member ID" }, "email": { "type": "string", "format": "email", "description": "Member's email address" }, "role": { "type": "string", "description": "Member's role" } } }, "Invite": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "description": "Invited email address" } } }, "WebSocketEvent": { "type": "object", "required": [ "event" ], "properties": { "event": { "type": "string", "description": "The event type", "enum": [ "connected", "newMessage", "newRelease" ] }, "aliasId": { "type": "string", "description": "The alias ID (present in connected event)" }, "mailbox": { "type": "string", "description": "The mailbox path (present in newMessage event)", "example": "INBOX" }, "uid": { "type": "integer", "description": "The message UID (present in newMessage event)", "example": 123 }, "release": { "type": "object", "description": "The release object (present in newRelease event)", "properties": { "tagName": { "type": "string", "description": "Git tag name of the release" }, "name": { "type": "string", "description": "Release title" }, "htmlUrl": { "type": "string", "description": "URL to the release page on GitHub" } } } } }, "PushToken": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique push token document ID" }, "alias": { "type": "string", "description": "Alias ID this token belongs to" }, "platform": { "type": "string", "enum": [ "apns", "fcm", "unified-push", "web-push" ], "description": "Push notification platform" }, "token": { "type": "string", "description": "Device token, registration token, or push endpoint URL" }, "device_name": { "type": "string", "description": "Optional human-readable device name" }, "last_used_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Last successful push delivery timestamp" }, "failure_count": { "type": "integer", "description": "Consecutive delivery failure count (auto-pruned at 3)" }, "expires_at": { "type": "string", "format": "date-time", "description": "Token expiry (auto-extended on successful delivery)" }, "created_at": { "type": "string", "format": "date-time", "description": "Registration timestamp" }, "updated_at": { "type": "string", "format": "date-time", "description": "Last update timestamp" }, "object": { "type": "string", "enum": [ "push_token" ], "description": "Object type identifier" } } }, "PushTokenInput": { "type": "object", "required": [ "platform", "token" ], "properties": { "platform": { "type": "string", "enum": [ "apns", "fcm", "unified-push", "web-push" ], "description": "Push notification platform" }, "token": { "type": "string", "maxLength": 4096, "description": "Device token (APNs hex), registration token (FCM), HTTPS endpoint URL (UnifiedPush), or JSON PushSubscription (Web Push)" }, "device_name": { "type": "string", "maxLength": 255, "description": "Optional human-readable device name for management" }, "alias_id": { "type": "string", "description": "Required when using API token authentication. The alias ID to register the token for." } } }, "PushTokenDeletion": { "type": "object", "properties": { "deleted_count": { "type": "integer", "description": "Number of tokens deleted" }, "object": { "type": "string", "enum": [ "push_token_deletion" ] } } } }, "parameters": { "page": { "name": "page", "in": "query", "description": "Page of results to return. If not specified, value will be 1. Must be a number greater than or equal to 1.", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, "limit": { "name": "limit", "in": "query", "description": "Number of results to return per page. Defaults to 25 if not specified. Must be a number greater than or equal to 1, and less than or equal to 100.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } }, "pagination": { "name": "pagination", "in": "query", "description": "Opt-in to pagination before November 1st, 2024", "schema": { "type": "boolean" } }, "domainId": { "name": "domain_id", "in": "path", "required": true, "description": "Domain ID", "schema": { "type": "string" } }, "aliasId": { "name": "alias_id", "in": "path", "required": true, "description": "Alias ID", "schema": { "type": "string" } }, "memberId": { "name": "member_id", "in": "path", "required": true, "description": "Member ID", "schema": { "type": "string" } }, "emailId": { "name": "id", "in": "path", "required": true, "description": "Email ID or Message-ID. You can pass either the unique email ID (e.g., '683fbe4d5baef1b583a11e54') or the email's Message-ID header value (e.g., '1a04fee3-5230-4a85-9111-a2c376835885@forwardemail.net').", "schema": { "type": "string" } }, "contactId": { "name": "id", "in": "path", "required": true, "description": "Contact ID", "schema": { "type": "string" } }, "calendarId": { "name": "id", "in": "path", "required": true, "description": "Calendar ID", "schema": { "type": "string" } }, "folderId": { "name": "id", "in": "path", "required": true, "description": "Folder ID or path", "schema": { "type": "string" } }, "messageId": { "name": "id", "in": "path", "required": true, "description": "Message ID", "schema": { "type": "string" } }, "labelKeyword": { "name": "keyword", "in": "path", "required": true, "description": "IMAP keyword used as the label identifier", "schema": { "type": "string" } } }, "responses": { "Error": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "BadRequest": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Unauthorized": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Forbidden": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "NotFound": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Conflict": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "PreconditionFailed": { "description": "Precondition Failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "TooManyRequests": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "InternalServerError": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "NotImplemented": { "description": "Not Implemented", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "BadGateway": { "description": "Bad Gateway", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "ServiceUnavailable": { "description": "Service Unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "GatewayTimeout": { "description": "Gateway Time-out", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "paths": { "/v1/account": { "get": { "tags": [ "Account" ], "summary": "Retrieve account", "description": "Retrieve your account information.\n\n**Authentication:** This endpoint supports both API token authentication and alias credentials authentication.\n\n- **User Account (API Token):** When authenticated with your API token, this endpoint returns your user account information including plan details, email, and API token.\n\n- **Alias Account (Alias Credentials):** When authenticated with alias credentials (email and generated password), this endpoint returns alias/mailbox information including storage used/quota and a nested `settings` object (mail special folders, label settings, and alias defaults). This is useful for IMAP/POP3/CalDAV/CardDAV clients to check storage status and preferences.", "operationId": "retrieveAccount", "security": [ { "ApiKeyAuth": [] }, { "AliasAuth": [] } ], "responses": { "200": { "description": "Account retrieved successfully", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Account" }, { "$ref": "#/components/schemas/AliasAccount" } ] }, "examples": { "userAccount": { "summary": "User Account (API Token Authentication)", "description": "Response when authenticated with API token", "value": { "sessions": [], "has_newsletter": true, "plan": "enhanced_protection", "email": "user@example.com", "max_quota_per_alias": 10737418240, "full_email": "user@example.com", "display_name": "John Doe", "otp_enabled": false, "last_locale": "en", "address_country": "US", "id": "683fb2e81cc5d449a0d4cd9d", "object": "user", "locale": "en", "created_at": "2025-06-04T02:43:52.646Z", "updated_at": "2025-06-04T02:43:55.350Z", "address_html": "", "api_token": "15ac16ae21784aa2cb4d5508" } }, "aliasAccount": { "summary": "Alias Account (Alias Credentials Authentication)", "description": "Response when authenticated with alias email and generated password. Useful for IMAP/POP3/CalDAV/CardDAV storage information.", "value": { "id": "683fb2e81cc5d449a0d4cd9e", "object": "alias", "name": "user", "email": "user@example.com", "domain_id": "683fb2e81cc5d449a0d4cd9f", "domain_name": "example.com", "storage_used": 524288000, "storage_quota": 10737418240, "has_imap": true, "has_pgp": false, "public_key": "", "has_smime": false, "smime_certificate": "", "has_wkd_disabled": false, "locale": "en", "settings": { "mail": { "archive_folder": null, "sent_folder": null, "drafts_folder": null }, "label_settings": {}, "aliases": { "defaults": {} } }, "created_at": "2025-06-04T02:43:52.646Z", "updated_at": "2025-06-04T02:43:55.350Z" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "put": { "tags": [ "Account" ], "summary": "Update account", "description": "Update your account information.\n\n- **User Account (API Token):** Update user profile fields.\n- **Alias Account (Alias Credentials):** Update alias-scoped settings using the nested `settings` object. Legacy flat fields are accepted for compatibility. The response matches `GET /v1/account`.", "operationId": "updateAccount", "security": [ { "ApiKeyAuth": [] }, { "AliasAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "settings": { "type": "object", "description": "Alias settings (alias authentication only)", "properties": { "mail": { "type": "object", "properties": { "archive_folder": { "type": "string", "nullable": true, "description": "Alias mail archive folder" }, "sent_folder": { "type": "string", "nullable": true, "description": "Alias mail sent folder" }, "drafts_folder": { "type": "string", "nullable": true, "description": "Alias mail drafts folder" } } }, "label_settings": { "type": "object", "description": "Alias label map keyed by keyword", "additionalProperties": { "$ref": "#/components/schemas/SettingsLabelUpdate" } }, "aliases": { "type": "object", "properties": { "defaults": { "type": "object", "description": "Free-form alias defaults such as display_name or signature", "additionalProperties": true } } } } }, "display_name": { "type": "string", "description": "Display name" }, "locale": { "type": "string", "description": "Locale preference" }, "email": { "type": "string", "format": "email", "description": "Updated email address (user authentication only)" }, "avatar_url": { "type": "string", "format": "uri", "description": "Avatar URL (user authentication only)" } } } } } }, "responses": { "200": { "description": "Account updated successfully", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Account" }, { "$ref": "#/components/schemas/AliasAccount" } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v1/account/api-token": { "delete": { "tags": [ "Account" ], "summary": "Disable API token", "description": "`DELETE /v1/account/api-token` immediately disables the authenticated API token. The response is `{ \"api_token_disabled\": true }`.\n\nThe disabled token can no longer authenticate HTTP API or WebSocket requests. To re-enable API access, sign in to [My Security](/my-account/security) and reset the token, which generates a replacement. Alias-password authentication is unchanged.", "operationId": "disableApiToken", "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "API token disabled successfully", "content": { "application/json": { "schema": { "type": "object", "required": [ "api_token_disabled" ], "properties": { "api_token_disabled": { "type": "boolean", "description": "True after the authenticated API token has been disabled." } } }, "example": { "api_token_disabled": true } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v1/contacts": { "get": { "tags": [ "Contacts" ], "summary": "List contacts", "description": "Retrieve a list of all contacts for the authenticated alias. This endpoint supports pagination and returns contacts in CardDAV format.", "operationId": "listContacts", "security": [ { "AliasAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/limit" } ], "responses": { "200": { "description": "Contacts retrieved successfully", "headers": { "X-Page-Count": { "description": "Total number of pages", "schema": { "type": "integer" } }, "X-Page-Current": { "description": "Current page number", "schema": { "type": "integer" } }, "X-Page-Size": { "description": "Number of items on current page", "schema": { "type": "integer" } }, "X-Item-Count": { "description": "Total number of items", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Contact" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "post": { "tags": [ "Contacts" ], "summary": "Create contact", "description": "Create a new contact. You can provide either vCard content directly or individual contact fields that will be converted to vCard format. If a contact with the same ID already exists, a conflict error will be returned.", "operationId": "createContact", "security": [ { "AliasAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactInput" } } } }, "responses": { "201": { "description": "Contact created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Contact" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v1/contacts/{id}": { "get": { "tags": [ "Contacts" ], "summary": "Retrieve contact", "description": "Retrieve a specific contact by its ID. The contact is returned in the standard Contact format with vCard content and parsed fields.", "operationId": "retrieveContact", "security": [ { "AliasAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/contactId" } ], "responses": { "200": { "description": "Contact retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Contact" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "put": { "tags": [ "Contacts" ], "summary": "Update contact", "description": "Update an existing contact. You can provide either updated vCard content or individual fields to update. The contact's vCard will be regenerated if individual fields are provided.", "operationId": "updateContact", "security": [ { "AliasAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/contactId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactUpdateInput" } } } }, "responses": { "200": { "description": "Contact updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Contact" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "delete": { "tags": [ "Contacts" ], "summary": "Delete contact", "description": "Delete a specific contact permanently. This action cannot be undone.", "operationId": "deleteContact", "security": [ { "AliasAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/contactId" } ], "responses": { "200": { "description": "Contact deleted successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Contact" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v1/calendars": { "get": { "tags": [ "Calendars" ], "summary": "List calendars", "description": "Retrieve a list of all calendars for the authenticated alias. This endpoint supports pagination and returns calendars in CalDAV format.", "operationId": "listCalendars", "security": [ { "AliasAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/limit" } ], "responses": { "200": { "description": "Calendars retrieved successfully", "headers": { "X-Page-Count": { "description": "Total number of pages", "schema": { "type": "integer" } }, "X-Page-Current": { "description": "Current page number", "schema": { "type": "integer" } }, "X-Page-Size": { "description": "Number of items on current page", "schema": { "type": "integer" } }, "X-Item-Count": { "description": "Total number of items", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Calendar" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "post": { "tags": [ "Calendars" ], "summary": "Create calendar", "description": "Create a new calendar. The calendar name is required, while other properties like color, timezone, and description are optional. If a calendar with the same name already exists, a conflict error will be returned.", "operationId": "createCalendar", "security": [ { "AliasAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CalendarInput" } } } }, "responses": { "201": { "description": "Calendar created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Calendar" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v1/calendars/{id}": { "get": { "tags": [ "Calendars" ], "summary": "Retrieve calendar", "description": "Retrieve a specific calendar by its ID. The calendar is returned with all its properties including name, description, color, timezone, and order.", "operationId": "retrieveCalendar", "security": [ { "AliasAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/calendarId" } ], "responses": { "200": { "description": "Calendar retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Calendar" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "put": { "tags": [ "Calendars" ], "summary": "Update calendar", "description": "Update an existing calendar. You can update any of the calendar properties including name, description, color, timezone, and order. If you change the name to one that already exists, a conflict error will be returned.", "operationId": "updateCalendar", "security": [ { "AliasAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/calendarId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CalendarUpdateInput" } } } }, "responses": { "200": { "description": "Calendar updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Calendar" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "delete": { "tags": [ "Calendars" ], "summary": "Delete calendar", "description": "Delete a specific calendar permanently. This action cannot be undone and will also delete all events within the calendar.", "operationId": "deleteCalendar", "security": [ { "AliasAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/calendarId" } ], "responses": { "200": { "description": "Calendar deleted successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Calendar" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v1/calendar-events": { "get": { "tags": [ "Calendar Events" ], "summary": "List calendar events", "description": "Retrieve a list of calendar events for the authenticated alias. This endpoint supports pagination and filtering by calendar, date range, and deletion status.", "operationId": "listCalendarEvents", "security": [ { "AliasAuth": [] } ], "parameters": [ { "name": "calendar_id", "in": "query", "description": "Filter events by calendar ID", "required": false, "schema": { "type": "string" } }, { "name": "start_date", "in": "query", "description": "Filter events starting from this date (ISO 8601 format)", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "end_date", "in": "query", "description": "Filter events ending before this date (ISO 8601 format)", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "include_deleted", "in": "query", "description": "Include soft-deleted events in results", "required": false, "schema": { "type": "boolean", "default": false } }, { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/limit" } ], "responses": { "200": { "description": "List of calendar events", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/CalendarEvent" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "post": { "tags": [ "Calendar Events" ], "summary": "Create calendar event", "description": "Create a new calendar event with iCalendar data. The event will be validated and parsed to extract common properties for easy access.", "operationId": "createCalendarEvent", "security": [ { "AliasAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CalendarEventInput" } } } }, "responses": { "200": { "description": "Calendar event created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CalendarEvent" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v1/calendar-events/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Calendar event ID", "schema": { "type": "string" } } ], "get": { "tags": [ "Calendar Events" ], "summary": "Retrieve calendar event", "description": "Retrieve a specific calendar event by its ID. The event is returned with all its properties including parsed iCalendar data.", "operationId": "retrieveCalendarEvent", "security": [ { "AliasAuth": [] } ], "responses": { "200": { "description": "Calendar event retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CalendarEvent" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "put": { "tags": [ "Calendar Events" ], "summary": "Update calendar event", "description": "Update a specific calendar event. You can modify the iCalendar data or move the event to a different calendar.", "operationId": "updateCalendarEvent", "security": [ { "AliasAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CalendarEventUpdateInput" } } } }, "responses": { "200": { "description": "Calendar event updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CalendarEvent" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "delete": { "tags": [ "Calendar Events" ], "summary": "Delete calendar event", "description": "Soft delete a specific calendar event. The event will be marked as deleted but not permanently removed from the database.", "operationId": "deleteCalendarEvent", "security": [ { "AliasAuth": [] } ], "responses": { "200": { "description": "Calendar event deleted successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CalendarEvent" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v1/folders": { "get": { "tags": [ "Folders" ], "summary": "List folders", "description": "Retrieve a list of all IMAP folders/mailboxes for the authenticated alias. This endpoint supports pagination and filtering by subscription status.", "operationId": "listFolders", "security": [ { "AliasAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/limit" }, { "name": "subscribed", "in": "query", "description": "Filter folders by subscription status", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "Folders retrieved successfully", "headers": { "X-Page-Count": { "description": "Total number of pages", "schema": { "type": "integer" } }, "X-Page-Current": { "description": "Current page number", "schema": { "type": "integer" } }, "X-Page-Size": { "description": "Number of items on current page", "schema": { "type": "integer" } }, "X-Item-Count": { "description": "Total number of items", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Folder" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "post": { "tags": [ "Folders" ], "summary": "Create folder", "description": "Create a new IMAP folder/mailbox. The folder path is required and can include parent folders (e.g., 'INBOX/Subfolder'). If the parent folders don't exist, they will be created automatically.", "operationId": "createFolder", "security": [ { "AliasAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FolderInput" } } } }, "responses": { "201": { "description": "Folder created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Folder" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v1/folders/{id}": { "get": { "tags": [ "Folders" ], "summary": "Retrieve folder", "description": "Retrieve a specific folder by its ID or path. You can use either the folder's ObjectID or its full path (e.g., 'INBOX/Subfolder') as the identifier.", "operationId": "retrieveFolder", "security": [ { "AliasAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/folderId" } ], "responses": { "200": { "description": "Folder retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Folder" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "put": { "tags": [ "Folders" ], "summary": "Update folder", "description": "Update/rename an existing folder. This operation renames the folder to the new path specified in the request body. You can use either the folder's ObjectID or its current path as the identifier.", "operationId": "updateFolder", "security": [ { "AliasAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/folderId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FolderUpdateInput" } } } }, "responses": { "200": { "description": "Folder updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Folder" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "delete": { "tags": [ "Folders" ], "summary": "Delete folder", "description": "Delete a specific folder permanently. This action cannot be undone and will also delete all messages within the folder. You can use either the folder's ObjectID or its path as the identifier.", "operationId": "deleteFolder", "security": [ { "AliasAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/folderId" } ], "responses": { "200": { "description": "Folder deleted successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Folder" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v1/messages": { "get": { "tags": [ "Messages" ], "summary": "List and search messages", "description": "Retrieve a list of messages with advanced search and filtering capabilities. This endpoint supports pagination and comprehensive search across message content, headers, flags, and metadata. You can search by folder, flags, content, headers, date ranges, size, and more.", "operationId": "listMessages", "security": [ { "AliasAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/limit" }, { "name": "folder", "in": "query", "description": "Filter messages by folder path", "schema": { "type": "string" } }, { "name": "is_unread", "in": "query", "description": "Filter by read status", "schema": { "type": "boolean" } }, { "name": "is_flagged", "in": "query", "description": "Filter by flagged status", "schema": { "type": "boolean" } }, { "name": "is_deleted", "in": "query", "description": "Filter by deleted status", "schema": { "type": "boolean" } }, { "name": "is_draft", "in": "query", "description": "Filter by draft status", "schema": { "type": "boolean" } }, { "name": "is_junk", "in": "query", "description": "Filter by junk/spam status", "schema": { "type": "boolean" } }, { "name": "is_copied", "in": "query", "description": "Filter by copied status", "schema": { "type": "boolean" } }, { "name": "is_encrypted", "in": "query", "description": "Filter by encryption status (PGP/MIME or S/MIME)", "schema": { "type": "boolean" } }, { "name": "is_searchable", "in": "query", "description": "Filter by searchable status", "schema": { "type": "boolean" } }, { "name": "is_expired", "in": "query", "description": "Filter by expired status", "schema": { "type": "boolean" } }, { "name": "has_attachments", "in": "query", "description": "Filter by attachment presence", "schema": { "type": "boolean" } }, { "name": "has_attachment", "in": "query", "description": "Filter by attachment presence (alias for has_attachments)", "schema": { "type": "boolean" } }, { "name": "subject", "in": "query", "description": "Search in message subject", "schema": { "type": "string" } }, { "name": "body", "in": "query", "description": "Search in message body/text", "schema": { "type": "string" } }, { "name": "text", "in": "query", "description": "Search in message text (alias for body)", "schema": { "type": "string" } }, { "name": "headers", "in": "query", "description": "Search in all message headers", "schema": { "type": "string" } }, { "name": "message_id", "in": "query", "description": "Search by Message-ID header", "schema": { "type": "string" } }, { "name": "search", "in": "query", "description": "General search across headers and text", "schema": { "type": "string" } }, { "name": "q", "in": "query", "description": "General search (alias for search)", "schema": { "type": "string" } }, { "name": "since", "in": "query", "description": "Filter messages since this date (ISO 8601 format)", "schema": { "type": "string", "format": "date-time" } }, { "name": "before", "in": "query", "description": "Filter messages before this date (ISO 8601 format)", "schema": { "type": "string", "format": "date-time" } }, { "name": "min_size", "in": "query", "description": "Filter messages with minimum size in bytes", "schema": { "type": "integer" } }, { "name": "max_size", "in": "query", "description": "Filter messages with maximum size in bytes", "schema": { "type": "integer" } }, { "name": "from", "in": "query", "description": "Search by From header", "schema": { "type": "string" } }, { "name": "to", "in": "query", "description": "Search by To header", "schema": { "type": "string" } }, { "name": "cc", "in": "query", "description": "Search by CC header", "schema": { "type": "string" } }, { "name": "bcc", "in": "query", "description": "Search by BCC header", "schema": { "type": "string" } }, { "name": "date", "in": "query", "description": "Search by Date header", "schema": { "type": "string" } }, { "name": "reply-to", "in": "query", "description": "Search by Reply-To header", "schema": { "type": "string" } }, { "name": "lightweight", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "true", "false" ], "default": "false" }, "description": "When set to \"true\", returns metadata-only responses without nodemailer or raw fields. This significantly improves performance by skipping full MIME tree reconstruction and attachment body fetching. Useful for building message lists where only metadata (subject, flags, dates, folder, size) is needed." } ], "responses": { "200": { "description": "Messages retrieved successfully", "headers": { "X-Page-Count": { "description": "Total number of pages", "schema": { "type": "integer" } }, "X-Page-Current": { "description": "Current page number", "schema": { "type": "integer" } }, "X-Page-Size": { "description": "Number of items on current page", "schema": { "type": "integer" } }, "X-Item-Count": { "description": "Total number of items", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Message" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "post": { "tags": [ "Messages" ], "summary": "Create message", "description": "Create/append a new message to a folder. This endpoint accepts standard Nodemailer message format and allows you to specify the target folder, initial flags, and labels. If the target folder doesn't exist, it will be created automatically.", "operationId": "createMessage", "security": [ { "AliasAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageInput" } } } }, "responses": { "201": { "description": "Message created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Message" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v1/messages/{id}": { "get": { "tags": [ "Messages" ], "summary": "Retrieve message", "description": "Retrieve a specific message by its ID. By default, the response includes the parsed Nodemailer object and raw message content. You can control what's included using query parameters.", "operationId": "retrieveMessage", "security": [ { "AliasAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/messageId" }, { "name": "eml", "in": "query", "description": "Return raw EML format instead of JSON", "schema": { "type": "boolean", "default": false } }, { "name": "nodemailer", "in": "query", "description": "Include parsed Nodemailer object", "schema": { "type": "boolean", "default": true } }, { "name": "attachments", "in": "query", "description": "Include attachments in Nodemailer object", "schema": { "type": "boolean", "default": true } }, { "name": "raw", "in": "query", "description": "Include raw message content", "schema": { "type": "boolean", "default": true } } ], "responses": { "200": { "description": "Message retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Message" } }, "message/rfc822": { "description": "Raw EML format (when ?eml=true)", "schema": { "type": "string" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "put": { "tags": [ "Messages" ], "summary": "Update message", "description": "Update an existing message. You can modify the message flags, labels, or move it to a different folder. If the target folder doesn't exist, it will be created automatically.", "operationId": "updateMessage", "security": [ { "AliasAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/messageId" }, { "name": "eml", "in": "query", "description": "Return raw EML format instead of JSON", "schema": { "type": "boolean", "default": false } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageUpdateInput" } } } }, "responses": { "200": { "description": "Message updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Message" } }, "message/rfc822": { "description": "Raw EML format (when ?eml=true)", "schema": { "type": "string" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "delete": { "tags": [ "Messages" ], "summary": "Delete message", "description": "Delete a specific message permanently. This action cannot be undone and will permanently remove the message from storage. Unlike IMAP clients which typically move messages to Trash, this endpoint performs a hard delete.", "operationId": "deleteMessage", "security": [ { "AliasAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/messageId" } ], "responses": { "200": { "description": "Message deleted successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Message" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v1/logs/download": { "get": { "summary": "Download logs", "description": "**Download logs**\n\nDescription: Our API programmatically allows you to download logs for your account. Submitting a request to this endpoint will process all logs for your account and email them to you as an attachment (Gzip compressed CSV spreadsheet file) once complete.\n\nThis allows you to create background jobs with a Cron job or using Node.js job scheduling software Bree to receive logs whenever you desire. Note that this endpoint is limited to `10` requests per day.\n\nThe attachment is the lowercase form of `email-deliverability-logs-YYYY-MM-DD-h-mm-A-z.csv.gz` and the email itself contains a brief summary of the logs retrieved.\n\n\nThe CSV spreadsheet includes the following columns: Log ID, Session ID, Date, Level, Bounce Category, Bounce Action, Truth Source, SMTP Response, SMTP Code, From, From Allowlisted, To, Subject, Message-ID, MAIL FROM, RCPT TO, Client IP, Client Hostname, Client Allowlisted, Target Host, Target MX Hostname, Target MX IP, Target Type, Opportunistic TLS, Require TLS, MX Hostname, MX IP, SPF, DKIM, Delivered To, Delivery Time (ms), and Message Size (bytes).", "tags": [ "Logs" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "domain", "in": "query", "description": "Filter logs by fully qualified domain (\"FQDN\"). If not provided, all logs across all domains will be retrieved.", "schema": { "type": "string" } }, { "name": "q", "in": "query", "description": "Search for logs by email, domain, alias name, IP address, or date (M/Y, M/D/YY, M-D, M-D-YY, or M.D.YY format).", "schema": { "type": "string" } }, { "name": "bounce_category", "in": "query", "description": "Search for logs by a specific bounce category (e.g. \"blocklist\").", "schema": { "type": "string" } }, { "name": "response_code", "in": "query", "description": "Search for logs by a specific error response code (e.g. 421 or 550).", "schema": { "type": "integer" } }, { "name": "always_send_email", "in": "query", "description": "If set to `true` or `1`, an email will always be sent even if no logs are found. The email will indicate that no logs were available and will not contain an attachment.", "schema": { "type": "string", "enum": [ "true", "false", "1", "0" ] } } ], "responses": { "200": { "description": "Logs will be emailed as an attachment", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Logs will be emailed to you shortly" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/emails": { "get": { "summary": "List outbound SMTP emails", "description": "**List outbound SMTP emails**\n\nNote that this endpoint does not return property values for an email's `message`, `headers`, nor `rejectedErrors`.\n\nTo return those properties and their values, please use the Retrieve email endpoint with an email ID or Message-ID.\n\n**Authentication:** This endpoint supports both API token authentication and alias credentials authentication. You can authenticate using either your API key (recommended) or your alias email address and generated password.", "tags": [ "Emails" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "q", "in": "query", "description": "Search for emails by metadata.", "schema": { "type": "string" } }, { "name": "domain", "in": "query", "description": "Search for emails by domain name.", "schema": { "type": "string" } }, { "name": "is_scheduled", "in": "query", "description": "Filter for scheduled emails (emails with future send date). Set to 'true' to show only emails scheduled to be sent in the future.", "schema": { "type": "boolean" } }, { "name": "sort", "in": "query", "description": "Sort by a specific field (prefix with a single hyphen - to sort in the reverse direction of that field). Defaults to created_at if not set.", "schema": { "type": "string" } }, { "name": "page", "in": "query", "description": "See Pagination for more insight.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "See Pagination for more insight.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of outbound SMTP emails", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Email" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } }, "post": { "summary": "Create outbound SMTP email", "description": "Our API for creating an email is inspired by and leverages Nodemailer's message option configuration. Please defer to the [Nodemailer message configuration](https://nodemailer.com/message/) for all body parameters below.\n\nNote that with the exception of `envelope` and `dkim` (since we set those automatically for you), we support all Nodemailer options. We automatically set `disableFileAccess` and `disableUrlAccess` options to `true` for security purposes.\n\nYou should either pass the single option of `raw` with your raw full email including headers or pass individual body parameter options below.\n\nThis API endpoint will automatically encode emojis for you if they are found in the headers (e.g. a subject line of `Subject: 🤓 Hello` gets converted to `Subject: =?UTF-8?Q?=F0=9F=A4=93?= Hello` automatically). Our goal was to make an extremely developer-friendly and dummy-proof email API.\n\n**Scheduled Sending:** To schedule an email for future delivery, set the `date` field to a future timestamp (must be at least 1 minute ahead and no more than 30 days from now). The email will be held until the specified time. You can cancel it using the Delete email endpoint.\n\n**Authentication:** This endpoint supports both API token authentication and alias credentials authentication. You can authenticate using either your API key (recommended) or your alias email address and generated password. See the Authentication section in the API documentation for details.", "tags": [ "Emails" ], "security": [ { "ApiKeyAuth": [] }, { "AliasAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SMTP" } } } }, "responses": { "200": { "description": "Email sent successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Email sent successfully" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/v1/emails/limit": { "get": { "summary": "Get outbound SMTP email limit", "description": "This is a simple endpoint that returns a JSON object containing the `count` and `limit` for the number of daily SMTP outbound messages on a per account basis.", "tags": [ "Emails" ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Email limit information", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailLimit" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/v1/emails/{id}": { "parameters": [ { "$ref": "#/components/parameters/emailId" } ], "get": { "summary": "Retrieve outbound SMTP email", "description": "Retrieve a specific outbound SMTP email by ID or Message-ID. You can pass either the email's unique ID or its Message-ID header value.\n\n**Authentication:** This endpoint supports both API token authentication and alias credentials authentication.", "tags": [ "Emails" ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Email retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Email" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "delete": { "summary": "Delete outbound SMTP email", "description": "Email deletion will set the status to `\"rejected\"` (and subsequently not process it in the queue) if and only if the current status is one of `\"pending\"`, `\"queued\"`, or `\"deferred\"`. This is useful for canceling emails scheduled via a future `date` before they are sent. We may purge emails automatically after 30 days after they were created and/or sent – therefore you should keep a copy of outbound SMTP emails in your client, database, or application.\n\n**Authentication:** This endpoint supports both API token authentication and alias credentials authentication.", "tags": [ "Emails" ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Email deleted successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Email deleted successfully" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/domains": { "get": { "summary": "List domains", "description": "> [!NOTE]\n>As of November 1st, 2024 the API endpoints for List domains and List domain aliases will default to `1000` max results per page. If you would like to opt-in to this behavior early, you can pass `?paginate=true` as an additional querystring parameter to the URL for the endpoint query. See Pagination for more insight.", "tags": [ "Domains" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "q", "in": "query", "description": "Search for domains by metadata.", "schema": { "type": "string" } }, { "name": "domain", "in": "query", "description": "Search for domains by domain name.", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "description": "Sort by a specific field (prefix with a single hyphen - to sort in the reverse direction of that field). Defaults to created_at if not set.", "schema": { "type": "string" } }, { "name": "page", "in": "query", "description": "See Pagination for more insight.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "See Pagination for more insight.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of domains", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Domain" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } }, "post": { "summary": "Create domain", "description": "Creates a new domain in the system. This endpoint allows you to register a fully qualified domain name (FQDN) or IP address for use with the platform.\n\nOptional configuration options include assigning the domain to an existing team, setting a plan type (e.g., free, enhanced protection, or team), and configuring advanced protections such as spam filtering, virus scanning, and recipient verification. You can also configure whether a catch-all alias should be created by default, set a custom bounce webhook URL for SMTP failures, and define storage quota limits for email aliases on this domain. This endpoint performs domain-level validation and provisioning. If the `ignore_mx_check` option is enabled, MX record verification is skipped (recommended only for advanced routing setups). The response will contain full details of the created domain object, including DNS records needed for configuration.", "tags": [ "Domains" ], "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateDomainInput" } } } }, "responses": { "200": { "description": "Domain created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Domain" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/domains/{domain_id}": { "parameters": [ { "$ref": "#/components/parameters/domainId" } ], "get": { "summary": "Retrieve domain", "description": "Retrieve a specific domain", "tags": [ "Domains" ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Domain retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Domain" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "put": { "summary": "Update domain", "description": "Update a specific domain.", "tags": [ "Domains" ], "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateDomainInput" } } } }, "responses": { "200": { "description": "Domain updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Domain" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "delete": { "summary": "Delete domain", "description": "Delete a specific domain.", "tags": [ "Domains" ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Domain deleted successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Domain deleted successfully" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/domains/{domain_id}/verify-records": { "parameters": [ { "$ref": "#/components/parameters/domainId" } ], "get": { "summary": "Verify domain records", "description": "Verify DNS records for a specific domain.", "tags": [ "Domains" ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "DNS records successfully verified", "content": { "text/plain": { "schema": { "type": "string", "example": "Domain's DNS records have been verified." } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/domains/{domain_id}/verify-smtp": { "get": { "summary": "Verify domain SMTP records", "description": "Verifies the SMTP-related DNS records for the specified domain.", "operationId": "verifySmtpRecords", "tags": [ "Domains" ], "parameters": [ { "name": "domain_id", "in": "path", "required": true, "description": "Fully qualified domain name (FQDN) to verify", "schema": { "type": "string", "format": "hostname" } } ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "SMTP records successfully verified", "content": { "text/plain": { "schema": { "type": "string", "example": "You have successfully configured and verified DNS records for outbound SMTP." } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/v1/domains/{domain_id}/test-s3-connection": { "post": { "summary": "Test custom S3 connection", "description": "Tests the custom S3 storage connection for the specified domain. Verifies that the configured credentials are valid, the bucket exists, and write permissions are available. The domain must have custom S3 storage enabled and configured before testing.", "operationId": "testS3Connection", "tags": [ "Domains" ], "parameters": [ { "name": "domain_id", "in": "path", "required": true, "description": "Fully qualified domain name (FQDN) or domain ID", "schema": { "type": "string" } } ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "S3 connection test successful", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Successfully connected to your custom S3 storage. Credentials are valid and the bucket is accessible." } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/v1/domains/{domain_id}/catch-all-passwords": { "post": { "summary": "Create domain-wide catch-all password", "description": "Creates a domain-wide catch-all password. If no password is provided, a secure random one will be generated. Catch-all passwords are for SMTP sending only. For IMAP, POP3, CalDAV, CardDAV, and mailbox access, generate a password for the specific alias instead.", "tags": [ "Domains" ], "parameters": [ { "name": "domain_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The domain name to create the catch-all password for" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "new_password": { "type": "string", "description": "Your custom new password to use for the domain-wide catch-all password. Leave blank to generate a strong password. Custom mailbox passwords must be 128 characters or fewer, cannot start or end with whitespace, and cannot contain quotes or apostrophes. Catch-all passwords are for SMTP sending only. For IMAP, POP3, CalDAV, CardDAV, and mailbox access, generate a password for the specific alias instead." }, "description": { "type": "string", "description": "Description for organization purposes only." } } }, "example": { "new_password": "myCustomStrongPassword123!", "description": "Password for team-wide access" } } } }, "responses": { "200": { "description": "Successfully created a catch-all password", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the created catch-all password" }, "description": { "type": "string", "description": "Description of the catch-all password" } }, "required": [ "id", "description" ] }, "example": { "id": "6841ec462bd583c73d0632dd", "username": "*@quas.com", "password": "6Yq14XhAUaupdZE", "description": "foo bar" } } } } } }, "get": { "summary": "List domain-wide catch-all passwords", "description": "Returns a list of domain-wide catch-all passwords that are currently configured for the specified domain.", "operationId": "listCatchAllPasswords", "tags": [ "Domains" ], "parameters": [ { "name": "domain_id", "in": "path", "required": true, "description": "Fully qualified domain name (FQDN) for which to list catch-all passwords", "schema": { "type": "string", "format": "hostname" } } ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "List of domain-wide catch-all passwords", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the item", "example": "6841ec442bd583c73d0632d0" }, "description": { "type": "string", "description": "Description of the item", "example": "foo bar" } }, "required": [ "id", "description" ] }, "example": [ { "id": "6841ec442bd583c73d0632d0", "description": "" }, { "id": "6841ec462bd583c73d0632dd", "description": "foo bar" } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/v1/domains/{domain_id}/catch-all-passwords/{token_id}": { "delete": { "summary": "Remove domain-wide catch-all password", "description": "Deletes a domain-wide catch-all password using the provided token ID.", "tags": [ "Domains" ], "parameters": [ { "name": "domain_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The domain name associated with the catch-all password" }, { "name": "token_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The token ID of the domain-wide catch-all password to delete" } ], "responses": { "200": { "description": "Catch-all password successfully removed", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Catch-all password deleted successfully." } }, "example": { "id": "6841ec442bd583c73d0632d0", "description": "" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/domains/{domain_id}/invites": { "parameters": [ { "$ref": "#/components/parameters/domainId" } ], "get": { "summary": "Accept domain invite", "description": "Accept an invitation to a domain.", "tags": [ "Invites" ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Domain invite accepted successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Invite accepted successfully" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "post": { "summary": "Create domain invite", "description": ">[!IMPORTANT]\n>If the user being invited is already an accepted member of any other domains the admin inviting them is a member of, then it will auto-accept the invite and not send an email.", "tags": [ "Invites" ], "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "email" ], "properties": { "email": { "type": "string", "format": "email", "description": "Email address to invite to domain members list" }, "group": { "type": "string", "format": "string", "description": "Group to add the user to the domain membership with (can be one of `\"admin\"` or `\"user\"`)" } } } } } }, "responses": { "200": { "description": "Domain invite created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Invite" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "summary": "Remove domain invite", "description": "Remove an invitation to a domain.", "tags": [ "Invites" ], "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "email" ], "properties": { "email": { "type": "string", "format": "email", "description": "Email address to remove from domain members list" } } } } } }, "responses": { "200": { "description": "Domain invite removed successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Invite removed successfully" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/domains/{domain_id}/members/{member_id}": { "parameters": [ { "$ref": "#/components/parameters/domainId" }, { "$ref": "#/components/parameters/memberId" } ], "put": { "summary": "Update domain member", "description": "Update a domain member.", "tags": [ "Members" ], "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "group": { "required": true, "type": "string", "description": "Group to update the user to the domain membership with (can be one of `\"admin\"` or `\"user\"`)" } } } } } }, "responses": { "200": { "description": "Domain member updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Member" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "delete": { "summary": "Remove domain member", "description": "Remove a domain member.", "tags": [ "Members" ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Domain member removed successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Member removed successfully" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/domains/{domain_id}/aliases/{alias_id}/generate-password": { "post": { "summary": "Generate an alias password", "description": "Generate a password for an alias. If `emailed_instructions` is not provided, the response will contain the generated username and password.", "tags": [ "Aliases" ], "parameters": [ { "name": "domain_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Fully qualified domain name (FQDN)" }, { "name": "alias_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier of the alias" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenerateAliasPasswordInput" } } } }, "responses": { "200": { "description": "Alias credentials returned successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "username": { "type": "string", "example": "alias@yourdomain.com" }, "password": { "type": "string", "example": "some-generated-password" } }, "required": [ "username", "password" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/v1/domains/{domain_id}/aliases": { "parameters": [ { "$ref": "#/components/parameters/domainId" } ], "get": { "summary": "List domain aliases", "description": ">[!NOTE]\n>As of November 1st, 2024 the API endpoints for `List domains` and `List domain aliases` will default to `1000` max results per page. If you would like to opt-in to this behavior early, you can pass `?paginate=true` as an additional querystring parameter to the URL for the endpoint query. See Pagination for more insight.", "tags": [ "Aliases" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "q", "in": "query", "description": "Search for aliases in a domain by name, label, or recipient (RegExp supported)", "required": false, "schema": { "type": "string" } }, { "name": "name", "in": "query", "description": "Search for aliases in a domain by name (RegExp supported)", "required": false, "schema": { "type": "string" } }, { "name": "recipient", "in": "query", "description": "Search for aliases in a domain by recipient (RegExp supported)", "required": false, "schema": { "type": "string" } }, { "name": "sort", "in": "query", "description": "Sort by a specific field (prefix with a single hyphen - to sort in reverse). Defaults to created_at.", "required": false, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/limit" } ], "responses": { "200": { "description": "List of domain aliases", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Alias" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "post": { "summary": "Create new domain alias", "description": "Create a new alias for a specific domain. Note: this endpoint does not accept `password` or `new_password` fields. To set or change alias credentials, use the \"POST /v1/domains/:domain_id/aliases/:alias_id/generate-password\" endpoint.", "tags": [ "Aliases" ], "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AliasInput" } } } }, "responses": { "200": { "description": "Domain alias created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Alias" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/domains/{domain_id}/aliases/{alias_id}": { "parameters": [ { "$ref": "#/components/parameters/domainId" }, { "$ref": "#/components/parameters/aliasId" } ], "get": { "summary": "Retrieve domain alias", "description": "Retrieve a specific alias for a domain.", "tags": [ "Aliases" ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Domain alias retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Alias" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "put": { "summary": "Update domain alias", "description": "Update a specific alias for a domain. Note: this endpoint does not accept `password` or `new_password` fields. To set or change alias credentials, use the \"POST /v1/domains/:domain_id/aliases/:alias_id/generate-password\" endpoint.", "tags": [ "Aliases" ], "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AliasUpdateInput" } } } }, "responses": { "200": { "description": "Domain alias updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Alias" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" } } }, "delete": { "summary": "Delete domain alias", "description": "Delete a specific alias for a domain.", "tags": [ "Aliases" ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Domain alias deleted successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Alias deleted successfully" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/encrypt": { "post": { "summary": "Encrypt TXT Record", "description": "We allow you to encrypt records even on the free plan at no cost. Privacy should not be a feature, it should be inherently built-in to all aspects of a product. As highly requested in a [Privacy Guides discussion](https://discuss.privacyguides.net/t/forward-email-email-provider/13370) and on our [GitHub issues](https://github.com/forwardemail/forwardemail.net/issues/254) we've added this.", "tags": [ "Encrypt" ], "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "text" ], "properties": { "input": { "required": true, "type": "string", "description": "Any valid Forward Email plaintext TXT record" } } } } } }, "responses": { "200": { "description": "Text encrypted successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "encrypted": { "type": "string", "description": "Encrypted text" } } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "429": { "description": "Rate limit exceeded (50 requests for 'encrypt')", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/domains/{domain_id}/aliases/{alias_id}/sieve": { "get": { "summary": "List Sieve Scripts", "description": "List all Sieve scripts for an alias. Sieve is a powerful email filtering language defined in RFC 5228.", "tags": [ "Sieve Scripts" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "domain_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Domain ID or name" }, { "name": "alias_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Alias ID or name" } ], "responses": { "200": { "description": "List of Sieve scripts", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SieveScript" } } } } }, "401": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" } } }, "post": { "summary": "Create Sieve Script", "description": "Create a new Sieve script for an alias. The script will be validated before saving.", "tags": [ "Sieve Scripts" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "domain_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Domain ID or name" }, { "name": "alias_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Alias ID or name" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "content" ], "properties": { "name": { "type": "string", "description": "Script name" }, "content": { "type": "string", "description": "Sieve script content" }, "is_active": { "type": "boolean", "description": "Whether the script is active", "default": false }, "priority": { "type": "integer", "description": "Script priority (lower = higher priority)", "default": 0 } } } } } }, "responses": { "201": { "description": "Sieve script created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SieveScript" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" } } } }, "/v1/domains/{domain_id}/aliases/{alias_id}/sieve/{script_id}": { "get": { "summary": "Get Sieve Script", "description": "Get a specific Sieve script by ID or name.", "tags": [ "Sieve Scripts" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "domain_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Domain ID or name" }, { "name": "alias_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Alias ID or name" }, { "name": "script_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Sieve script ID or name" } ], "responses": { "200": { "description": "Sieve script details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SieveScript" } } } }, "401": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" } } }, "put": { "summary": "Update Sieve Script", "description": "Update an existing Sieve script. The script will be validated before saving.", "tags": [ "Sieve Scripts" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "domain_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Domain ID or name" }, { "name": "alias_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Alias ID or name" }, { "name": "script_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Sieve script ID or name" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "type": "string", "description": "Sieve script content" }, "description": { "type": "string", "description": "Script description" }, "activate": { "type": "boolean", "description": "Whether to activate the script after update", "default": false } } } } } }, "responses": { "200": { "description": "Sieve script updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SieveScript" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" } } }, "delete": { "summary": "Delete Sieve Script", "description": "Delete a Sieve script. Cannot delete an active script.", "tags": [ "Sieve Scripts" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "domain_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Domain ID or name" }, { "name": "alias_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Alias ID or name" }, { "name": "script_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Sieve script ID or name" } ], "responses": { "200": { "description": "Sieve script deleted" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" } } } }, "/v1/domains/{domain_id}/aliases/{alias_id}/sieve/{script_id}/activate": { "post": { "summary": "Activate Sieve Script", "description": "Activate a Sieve script. Only one script can be active at a time - activating a script will deactivate any currently active script.", "tags": [ "Sieve Scripts" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "domain_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Domain ID or name" }, { "name": "alias_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Alias ID or name" }, { "name": "script_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Sieve script ID or name" } ], "responses": { "200": { "description": "Sieve script activated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SieveScript" } } } }, "401": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" } } } }, "/v1/sieve-scripts": { "get": { "summary": "List Sieve Scripts (Alias Auth)", "description": "List all Sieve scripts for the authenticated alias. Uses alias authentication instead of API token.", "tags": [ "Sieve Scripts" ], "security": [ { "AliasAuth": [] } ], "responses": { "200": { "description": "List of Sieve scripts", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SieveScript" } } } } }, "401": { "$ref": "#/components/responses/Error" } } }, "post": { "summary": "Create Sieve Script (Alias Auth)", "description": "Create a new Sieve script for the authenticated alias. Uses alias authentication instead of API token.", "tags": [ "Sieve Scripts" ], "security": [ { "AliasAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "content" ], "properties": { "name": { "type": "string", "description": "Script name" }, "content": { "type": "string", "description": "Sieve script content" }, "description": { "type": "string", "description": "Script description" } } } } } }, "responses": { "201": { "description": "Sieve script created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SieveScript" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" } } } }, "/v1/sieve-scripts/{script_id}": { "get": { "summary": "Get Sieve Script (Alias Auth)", "description": "Get a specific Sieve script by ID or name for the authenticated alias.", "tags": [ "Sieve Scripts" ], "security": [ { "AliasAuth": [] } ], "parameters": [ { "name": "script_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Sieve script ID or name" } ], "responses": { "200": { "description": "Sieve script details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SieveScript" } } } }, "401": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" } } }, "put": { "summary": "Update Sieve Script (Alias Auth)", "description": "Update an existing Sieve script for the authenticated alias.", "tags": [ "Sieve Scripts" ], "security": [ { "AliasAuth": [] } ], "parameters": [ { "name": "script_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Sieve script ID or name" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "type": "string", "description": "Sieve script content" }, "description": { "type": "string", "description": "Script description" }, "activate": { "type": "boolean", "description": "Whether to activate the script after update", "default": false } } } } } }, "responses": { "200": { "description": "Sieve script updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SieveScript" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" } } }, "delete": { "summary": "Delete Sieve Script (Alias Auth)", "description": "Delete a Sieve script for the authenticated alias. Cannot delete an active script.", "tags": [ "Sieve Scripts" ], "security": [ { "AliasAuth": [] } ], "parameters": [ { "name": "script_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Sieve script ID or name" } ], "responses": { "200": { "description": "Sieve script deleted" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" } } } }, "/v1/sieve-scripts/{script_id}/activate": { "post": { "summary": "Activate Sieve Script (Alias Auth)", "description": "Activate a Sieve script for the authenticated alias. Only one script can be active at a time.", "tags": [ "Sieve Scripts" ], "security": [ { "AliasAuth": [] } ], "parameters": [ { "name": "script_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Sieve script ID or name" } ], "responses": { "200": { "description": "Sieve script activated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SieveScript" } } } }, "401": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" } } } }, "/v1/ws": { "get": { "tags": [ "WebSockets" ], "summary": "WebSocket Notifications", "description": "Connect to the WebSocket endpoint for real-time push notifications.\n\n**Connection URL:** `wss://api.forwardemail.net/v1/ws`\n\n**Authentication (Optional):**\n- **Authenticated Clients:** Provide credentials via `Authorization` header to receive both per-alias events (IMAP, CalDAV, CardDAV) and global broadcast events (`newRelease`).\n- **Unauthenticated Clients:** Connect without credentials to receive only global broadcast events (`newRelease`). This is useful for clients that only need to be notified of app updates.\n\n**Authentication Methods:**\n\nAuthentication **must** be provided via the `Authorization` header using HTTP Basic Authentication. Query parameters for authentication are **NOT supported**.\n\n**Option 1: Alias Password Authentication (Recommended)**\n\nUse your alias email address and generated password:\n\n```javascript\nconst ws = new WebSocket(\"wss://api.forwardemail.net/v1/ws\", {\n headers: {\n Authorization: `Basic ${btoa(\"user@domain.com:alias-password\")}`\n }\n});\n```\n\n**Option 2: API Token Authentication**\n\nUse your API token (requires `?alias_id=` query parameter):\n\n```javascript\nconst ws = new WebSocket(\"wss://api.forwardemail.net/v1/ws?alias_id=YOUR_ALIAS_ID\", {\n headers: {\n Authorization: `Basic ${btoa(\"YOUR_API_TOKEN:\")}` // Note: password is empty\n }\n});\n```\n\n**Option 3: Unauthenticated (Broadcast-Only)**\n\nConnect without authentication to receive only global broadcast events:\n\n```javascript\nconst ws = new WebSocket(\"wss://api.forwardemail.net/v1/ws\");\n```\n\n**Connection Responses:**\n\nUpon successful connection, the server sends a `connected` event:\n\n- **Authenticated:** `{\"event\":\"connected\",\"aliasId\":\"\"}`\n- **Unauthenticated:** `{\"event\":\"connected\",\"broadcastOnly\":true}`\n\nIf you receive `broadcastOnly: true`, your authentication failed or was not provided, and you will only receive global broadcast events.\n\n**msgpackr Encoding:** By default, messages are sent as JSON text frames. Pass `?msgpackr=true` to receive binary msgpackr-encoded frames for reduced bandwidth.\n\n**Behavior:**\n- Read-only channel: client messages are silently discarded\n- Server sends a `connected` event upon successful connection\n- Server sends periodic `ping` frames; client must respond with `pong`\n- Per-IP rate limit: 30 connections/minute\n- Per-alias connection limit (authenticated): 10 concurrent connections\n- Per-IP unauthenticated connection limit: 3 concurrent connections\n- Global connection limit: 10,000\n\n**Event Payloads:** Each event includes an `event` field indicating the type, plus a resource object (`message`, `contact`, `calendarEvent`, `calendar`, `addressBook`, or `release`) containing the full resource data mirroring the corresponding REST API response.\n\n**Per-Alias Events (Authenticated Only):**\n- **IMAP:** `newMessage`, `messagesMoved`, `messagesCopied`, `flagsUpdated`, `messagesExpunged`, `mailboxCreated`, `mailboxDeleted`, `mailboxRenamed`\n- **CalDAV:** `calendarCreated`, `calendarUpdated`, `calendarDeleted`, `calendarEventCreated`, `calendarEventUpdated`, `calendarEventDeleted`\n- **CardDAV:** `contactCreated`, `contactUpdated`, `contactDeleted`, `addressBookCreated`, `addressBookDeleted`\n\n**Broadcast Events (All Clients):**\n- `newRelease` — Broadcast when a new version of the Forward Email Mail App (https://github.com/forwardemail/mail.forwardemail.net) is published on GitHub. The server polls GitHub every 15 minutes and uses a content-based fingerprint to detect changes. **Asset Gating**: When a new release is detected but has no assets yet, the broadcast is deferred until assets appear.\n\n**Important Notes:**\n- Query parameters `?token=`, `?username=`, `?password=` are **NOT supported** for authentication\n- Authentication **must** be via `Authorization` header using HTTP Basic Authentication\n- If authentication fails, you will receive `broadcastOnly: true` or a `401 Unauthorized` error\n- For API token authentication, the `?alias_id=` query parameter is **required**", "operationId": "websocketNotifications", "parameters": [ { "name": "alias_id", "in": "query", "description": "**Required for API token authentication.** The alias ID to subscribe to. This parameter is only used when authenticating with an API token via the Authorization header.", "required": false, "schema": { "type": "string" } }, { "name": "msgpackr", "in": "query", "description": "Set to \"true\" to receive binary msgpackr-encoded frames instead of JSON text. Reduces bandwidth significantly for high-volume notifications.", "required": false, "schema": { "type": "string", "enum": [ "true", "false" ], "default": "false" } } ], "responses": { "101": { "description": "WebSocket connection established. Events are streamed as messages.", "content": { "application/json": { "schema": { "oneOf": [ { "title": "connected", "type": "object", "description": "Sent immediately after a successful connection. The payload differs for authenticated and unauthenticated clients.", "required": [ "event" ], "properties": { "event": { "type": "string", "enum": [ "connected" ] }, "alias_id": { "type": "string", "description": "The authenticated alias ID (present only for authenticated clients)" }, "broadcastOnly": { "type": "boolean", "description": "True if the client is unauthenticated and will only receive broadcast events (present only for unauthenticated clients)" }, "msgpackr": { "type": "boolean", "description": "Whether msgpackr encoding is enabled" } }, "oneOf": [ { "title": "Authenticated Example", "example": { "event": "connected", "alias_id": "507f1f77bcf86cd799439011", "msgpackr": false } }, { "title": "Unauthenticated Example", "example": { "event": "connected", "broadcastOnly": true, "msgpackr": false } } ] }, { "title": "newMessage", "type": "object", "description": "A new message was appended to a mailbox (IMAP APPEND or delivery).", "required": [ "event", "alias_id", "data" ], "properties": { "event": { "type": "string", "enum": [ "newMessage" ] }, "alias_id": { "type": "string" }, "data": { "type": "object", "required": [ "mailbox", "message" ], "properties": { "mailbox": { "type": "string", "description": "Mailbox path (e.g. \"INBOX\")" }, "message": { "type": "object", "description": "Full message object mirroring GET /v1/messages/:id response", "properties": { "id": { "type": "string" }, "folder_id": { "type": "string" }, "folder_path": { "type": "string" }, "thread_id": { "type": "string" }, "header_message_id": { "type": "string" }, "uid": { "type": "integer" }, "modseq": { "type": "integer" }, "flags": { "type": "array", "items": { "type": "string" } }, "labels": { "type": "array", "items": { "type": "string" } }, "from": { "type": "string", "description": "Sender address (e.g. 'Alice ')" }, "subject": { "type": "string" }, "size": { "type": "integer" }, "is_unread": { "type": "boolean" }, "is_flagged": { "type": "boolean" }, "is_draft": { "type": "boolean" }, "is_junk": { "type": "boolean" }, "is_encrypted": { "type": "boolean", "description": "Whether the message is encrypted (PGP/MIME or S/MIME)" }, "is_deleted": { "type": "boolean" }, "is_copied": { "type": "boolean" }, "is_searchable": { "type": "boolean" }, "is_expired": { "type": "boolean" }, "has_attachment": { "type": "boolean" }, "retention_date": { "type": "string", "format": "date-time" }, "remote_address": { "type": "string" }, "transaction": { "type": "string" }, "root_id": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "internal_date": { "type": "string", "format": "date-time" }, "header_date": { "type": "string", "format": "date-time" }, "object": { "type": "string", "enum": [ "message" ] } } } } } }, "example": { "event": "newMessage", "alias_id": "507f1f77bcf86cd799439011", "data": { "mailbox": "INBOX", "message": { "id": "60d5f484f1a2c8b1f8e4e1a1", "folder_id": "60d5f484f1a2c8b1f8e4e1a0", "folder_path": "INBOX", "uid": 42, "modseq": 100, "flags": [], "labels": [], "subject": "Hello World", "size": 1234, "is_unread": true, "is_flagged": false, "is_draft": false, "is_junk": false, "has_attachment": false, "from": "sender@example.com", "object": "message", "is_encrypted": false, "is_deleted": false, "is_copied": false, "is_searchable": true, "is_expired": false, "remote_address": "127.0.0.1", "transaction": "APPEND" } } } }, { "title": "messagesMoved", "type": "object", "description": "Messages were moved between mailboxes.", "required": [ "event", "alias_id", "data" ], "properties": { "event": { "type": "string", "enum": [ "messagesMoved" ] }, "alias_id": { "type": "string" }, "data": { "type": "object", "properties": { "sourceMailbox": { "type": "string", "description": "Source mailbox ID" }, "destinationMailbox": { "type": "string", "description": "Destination mailbox ID" }, "destinationPath": { "type": "string", "description": "Destination mailbox path" }, "sourceUid": { "type": "array", "items": { "type": "integer" }, "description": "UIDs in source mailbox" }, "destinationUid": { "type": "array", "items": { "type": "integer" }, "description": "New UIDs in destination mailbox" } } } }, "example": { "event": "messagesMoved", "alias_id": "507f1f77bcf86cd799439011", "data": { "sourceMailbox": "60d5f484f1a2c8b1f8e4e1a0", "destinationMailbox": "60d5f484f1a2c8b1f8e4e1a2", "destinationPath": "Trash", "sourceUid": [ 1, 2, 3 ], "destinationUid": [ 10, 11, 12 ] } } }, { "title": "messagesCopied", "type": "object", "description": "Messages were copied to another mailbox.", "required": [ "event", "alias_id", "data" ], "properties": { "event": { "type": "string", "enum": [ "messagesCopied" ] }, "alias_id": { "type": "string" }, "data": { "type": "object", "properties": { "sourceMailbox": { "type": "string" }, "destinationMailbox": { "type": "string" }, "destinationPath": { "type": "string" }, "sourceUid": { "type": "array", "items": { "type": "integer" } }, "destinationUid": { "type": "array", "items": { "type": "integer" } } } } }, "example": { "event": "messagesCopied", "alias_id": "507f1f77bcf86cd799439011", "data": { "sourceMailbox": "60d5f484f1a2c8b1f8e4e1a0", "destinationMailbox": "60d5f484f1a2c8b1f8e4e1a3", "destinationPath": "Archive", "sourceUid": [ 5 ], "destinationUid": [ 1 ] } } }, { "title": "flagsUpdated", "type": "object", "description": "Message flags were changed (e.g. \\\\Seen, \\\\Flagged, \\\\Deleted).", "required": [ "event", "alias_id", "data" ], "properties": { "event": { "type": "string", "enum": [ "flagsUpdated" ] }, "alias_id": { "type": "string" }, "data": { "type": "object", "properties": { "mailbox": { "type": "string", "description": "Mailbox ID" }, "uids": { "type": "array", "items": { "type": "integer" }, "description": "UIDs of affected messages" }, "flags": { "type": "object", "description": "Flag changes applied", "properties": { "set": { "type": "array", "items": { "type": "string" } }, "add": { "type": "array", "items": { "type": "string" } }, "remove": { "type": "array", "items": { "type": "string" } } } } } } }, "example": { "event": "flagsUpdated", "alias_id": "507f1f77bcf86cd799439011", "data": { "mailbox": "60d5f484f1a2c8b1f8e4e1a0", "uids": [ 1, 2 ], "flags": { "set": [ "\\\\Seen", "\\\\Flagged" ] } } } }, { "title": "messagesExpunged", "type": "object", "description": "Messages were permanently expunged from a mailbox.", "required": [ "event", "alias_id", "data" ], "properties": { "event": { "type": "string", "enum": [ "messagesExpunged" ] }, "alias_id": { "type": "string" }, "data": { "type": "object", "properties": { "mailbox": { "type": "string", "description": "Mailbox ID" } } } }, "example": { "event": "messagesExpunged", "alias_id": "507f1f77bcf86cd799439011", "data": { "mailbox": "60d5f484f1a2c8b1f8e4e1a0" } } }, { "title": "mailboxCreated", "type": "object", "description": "A new mailbox/folder was created.", "required": [ "event", "alias_id", "data" ], "properties": { "event": { "type": "string", "enum": [ "mailboxCreated" ] }, "alias_id": { "type": "string" }, "data": { "type": "object", "properties": { "path": { "type": "string", "description": "Mailbox path" }, "mailbox": { "type": "string", "description": "Mailbox ID" } } } }, "example": { "event": "mailboxCreated", "alias_id": "507f1f77bcf86cd799439011", "data": { "path": "Projects/Work", "mailbox": "60d5f484f1a2c8b1f8e4e1a5" } } }, { "title": "mailboxDeleted", "type": "object", "description": "A mailbox/folder was deleted.", "required": [ "event", "alias_id", "data" ], "properties": { "event": { "type": "string", "enum": [ "mailboxDeleted" ] }, "alias_id": { "type": "string" }, "data": { "type": "object", "properties": { "path": { "type": "string" }, "mailbox": { "type": "string" } } } }, "example": { "event": "mailboxDeleted", "alias_id": "507f1f77bcf86cd799439011", "data": { "path": "Old Folder", "mailbox": "60d5f484f1a2c8b1f8e4e1a5" } } }, { "title": "mailboxRenamed", "type": "object", "description": "A mailbox/folder was renamed.", "required": [ "event", "alias_id", "data" ], "properties": { "event": { "type": "string", "enum": [ "mailboxRenamed" ] }, "alias_id": { "type": "string" }, "data": { "type": "object", "properties": { "oldPath": { "type": "string" }, "newPath": { "type": "string" }, "mailbox": { "type": "string" } } } }, "example": { "event": "mailboxRenamed", "alias_id": "507f1f77bcf86cd799439011", "data": { "oldPath": "Old Name", "newPath": "New Name", "mailbox": "60d5f484f1a2c8b1f8e4e1a5" } } }, { "title": "calendarCreated", "type": "object", "description": "A new calendar was created.", "required": [ "event", "alias_id", "data" ], "properties": { "event": { "type": "string", "enum": [ "calendarCreated" ] }, "alias_id": { "type": "string" }, "data": { "type": "object", "required": [ "calendar" ], "properties": { "calendar": { "type": "object", "description": "Full calendar object mirroring GET /v1/calendars/:id response", "properties": { "id": { "type": "string" }, "calendarId": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "color": { "type": "string" }, "order": { "type": "integer" }, "timezone": { "type": "string" }, "readonly": { "type": "boolean" }, "synctoken": { "type": "string" }, "object": { "type": "string", "enum": [ "calendar" ] } } } } } }, "example": { "event": "calendarCreated", "alias_id": "507f1f77bcf86cd799439011", "data": { "calendar": { "id": "60d5f484f1a2c8b1f8e4e1b0", "calendarId": "work-calendar", "name": "Work", "description": "Work events", "color": "#FF5733", "order": 0, "timezone": "America/New_York", "readonly": false, "object": "calendar" } } } }, { "title": "calendarUpdated", "type": "object", "description": "A calendar was updated.", "required": [ "event", "alias_id", "data" ], "properties": { "event": { "type": "string", "enum": [ "calendarUpdated" ] }, "alias_id": { "type": "string" }, "data": { "type": "object", "required": [ "calendar" ], "properties": { "calendar": { "$ref": "#/paths/~1v1~1ws/get/responses/101/content/application~1json/schema/oneOf/10/properties/data/properties/calendar" } } } }, "example": { "event": "calendarUpdated", "alias_id": "507f1f77bcf86cd799439011", "data": { "calendar": { "id": "60d5f484f1a2c8b1f8e4e1b0", "calendarId": "work-calendar", "name": "Work (Updated)", "color": "#00FF00", "object": "calendar" } } } }, { "title": "calendarDeleted", "type": "object", "description": "A calendar was deleted.", "required": [ "event", "alias_id", "data" ], "properties": { "event": { "type": "string", "enum": [ "calendarDeleted" ] }, "alias_id": { "type": "string" }, "data": { "type": "object", "required": [ "calendar" ], "properties": { "calendar": { "type": "object", "properties": { "id": { "type": "string" }, "calendarId": { "type": "string" }, "name": { "type": "string" }, "object": { "type": "string", "enum": [ "calendar" ] } } } } } }, "example": { "event": "calendarDeleted", "alias_id": "507f1f77bcf86cd799439011", "data": { "calendar": { "id": "60d5f484f1a2c8b1f8e4e1b0", "calendarId": "work-calendar", "name": "Work", "object": "calendar" } } } }, { "title": "calendarEventCreated", "type": "object", "description": "A calendar event was created.", "required": [ "event", "alias_id", "data" ], "properties": { "event": { "type": "string", "enum": [ "calendarEventCreated" ] }, "alias_id": { "type": "string" }, "data": { "type": "object", "required": [ "calendarEvent" ], "properties": { "calendarEvent": { "type": "object", "description": "Full calendar event object with iCal data", "properties": { "id": { "type": "string" }, "eventId": { "type": "string" }, "calendarId": { "type": "string" }, "ical": { "type": "string", "description": "Full iCalendar (RFC 5545) data string" }, "href": { "type": "string" }, "object": { "type": "string", "enum": [ "calendar_event" ] } } } } } }, "example": { "event": "calendarEventCreated", "alias_id": "507f1f77bcf86cd799439011", "data": { "calendarEvent": { "id": "60d5f484f1a2c8b1f8e4e1c0", "eventId": "meeting-123.ics", "calendarId": "work-calendar", "ical": "BEGIN:VCALENDAR\\nVERSION:2.0\\nBEGIN:VEVENT\\nSUMMARY:Team Meeting\\nEND:VEVENT\\nEND:VCALENDAR", "href": "/dav/user@example.com/work-calendar/meeting-123.ics", "object": "calendar_event" } } } }, { "title": "calendarEventUpdated", "type": "object", "description": "A calendar event was updated.", "required": [ "event", "alias_id", "data" ], "properties": { "event": { "type": "string", "enum": [ "calendarEventUpdated" ] }, "alias_id": { "type": "string" }, "data": { "type": "object", "required": [ "calendarEvent" ], "properties": { "calendarEvent": { "$ref": "#/paths/~1v1~1ws/get/responses/101/content/application~1json/schema/oneOf/13/properties/data/properties/calendarEvent" } } } }, "example": { "event": "calendarEventUpdated", "alias_id": "507f1f77bcf86cd799439011", "data": { "calendarEvent": { "id": "60d5f484f1a2c8b1f8e4e1c0", "eventId": "meeting-123.ics", "calendarId": "work-calendar", "ical": "BEGIN:VCALENDAR\\nVERSION:2.0\\nBEGIN:VEVENT\\nSUMMARY:Team Meeting (Updated)\\nEND:VEVENT\\nEND:VCALENDAR", "object": "calendar_event" } } } }, { "title": "calendarEventDeleted", "type": "object", "description": "A calendar event was deleted.", "required": [ "event", "alias_id", "data" ], "properties": { "event": { "type": "string", "enum": [ "calendarEventDeleted" ] }, "alias_id": { "type": "string" }, "data": { "type": "object", "required": [ "calendarEvent" ], "properties": { "calendarEvent": { "type": "object", "properties": { "id": { "type": "string" }, "eventId": { "type": "string" }, "calendarId": { "type": "string" }, "ical": { "type": "string", "description": "Last known iCal data before deletion" }, "object": { "type": "string", "enum": [ "calendar_event" ] } } } } } }, "example": { "event": "calendarEventDeleted", "alias_id": "507f1f77bcf86cd799439011", "data": { "calendarEvent": { "id": "60d5f484f1a2c8b1f8e4e1c0", "eventId": "meeting-123.ics", "calendarId": "work-calendar", "object": "calendar_event" } } } }, { "title": "contactCreated", "type": "object", "description": "A contact was created.", "required": [ "event", "alias_id", "data" ], "properties": { "event": { "type": "string", "enum": [ "contactCreated" ] }, "alias_id": { "type": "string" }, "data": { "type": "object", "required": [ "contact" ], "properties": { "contact": { "type": "object", "description": "Full contact object with vCard data", "properties": { "id": { "type": "string" }, "contactId": { "type": "string" }, "addressBookId": { "type": "string" }, "fullName": { "type": "string" }, "content": { "type": "string", "description": "Full vCard (RFC 6350) data string" }, "etag": { "type": "string" }, "object": { "type": "string", "enum": [ "contact" ] } } } } } }, "example": { "event": "contactCreated", "alias_id": "507f1f77bcf86cd799439011", "data": { "contact": { "contactId": "john-doe.vcf", "addressBookId": "60d5f484f1a2c8b1f8e4e1d0", "fullName": "John Doe", "content": "BEGIN:VCARD\\nVERSION:3.0\\nFN:John Doe\\nEMAIL:john@example.com\\nEND:VCARD", "etag": "\"abc123\"", "object": "contact" } } } }, { "title": "contactUpdated", "type": "object", "description": "A contact was updated.", "required": [ "event", "alias_id", "data" ], "properties": { "event": { "type": "string", "enum": [ "contactUpdated" ] }, "alias_id": { "type": "string" }, "data": { "type": "object", "required": [ "contact" ], "properties": { "contact": { "$ref": "#/paths/~1v1~1ws/get/responses/101/content/application~1json/schema/oneOf/16/properties/data/properties/contact" } } } }, "example": { "event": "contactUpdated", "alias_id": "507f1f77bcf86cd799439011", "data": { "contact": { "id": "60d5f484f1a2c8b1f8e4e1e0", "contactId": "john-doe.vcf", "addressBookId": "60d5f484f1a2c8b1f8e4e1d0", "fullName": "John Doe (Updated)", "content": "BEGIN:VCARD\\nVERSION:3.0\\nFN:John Doe (Updated)\\nEMAIL:john@example.com\\nEND:VCARD", "etag": "\"def456\"", "object": "contact" } } } }, { "title": "contactDeleted", "type": "object", "description": "A contact was deleted.", "required": [ "event", "alias_id", "data" ], "properties": { "event": { "type": "string", "enum": [ "contactDeleted" ] }, "alias_id": { "type": "string" }, "data": { "type": "object", "required": [ "contact" ], "properties": { "contact": { "type": "object", "properties": { "id": { "type": "string" }, "contactId": { "type": "string" }, "addressBookId": { "type": "string" }, "fullName": { "type": "string" }, "content": { "type": "string", "description": "Last known vCard data before deletion" }, "object": { "type": "string", "enum": [ "contact" ] } } } } } }, "example": { "event": "contactDeleted", "alias_id": "507f1f77bcf86cd799439011", "data": { "contact": { "id": "60d5f484f1a2c8b1f8e4e1e0", "contactId": "john-doe.vcf", "addressBookId": "60d5f484f1a2c8b1f8e4e1d0", "fullName": "John Doe", "object": "contact" } } } }, { "title": "addressBookCreated", "type": "object", "description": "An address book was created.", "required": [ "event", "alias_id", "data" ], "properties": { "event": { "type": "string", "enum": [ "addressBookCreated" ] }, "alias_id": { "type": "string" }, "data": { "type": "object", "required": [ "addressBook" ], "properties": { "addressBook": { "type": "object", "properties": { "addressBookId": { "type": "string" }, "name": { "type": "string" }, "object": { "type": "string", "enum": [ "address_book" ] } } } } } }, "example": { "event": "addressBookCreated", "alias_id": "507f1f77bcf86cd799439011", "data": { "addressBook": { "addressBookId": "personal", "name": "Personal Contacts", "object": "address_book" } } } }, { "title": "addressBookDeleted", "type": "object", "description": "An address book was deleted.", "required": [ "event", "alias_id", "data" ], "properties": { "event": { "type": "string", "enum": [ "addressBookDeleted" ] }, "alias_id": { "type": "string" }, "data": { "type": "object", "required": [ "addressBook" ], "properties": { "addressBook": { "type": "object", "properties": { "id": { "type": "string" }, "addressBookId": { "type": "string" }, "name": { "type": "string" }, "object": { "type": "string", "enum": [ "address_book" ] } } } } } }, "example": { "event": "addressBookDeleted", "alias_id": "507f1f77bcf86cd799439011", "data": { "addressBook": { "id": "60d5f484f1a2c8b1f8e4e1f0", "addressBookId": "old-contacts", "name": "Old Contacts", "object": "address_book" } } } }, { "title": "newRelease", "type": "object", "description": "A new version of the Forward Email Mail App (https://github.com/forwardemail/mail.forwardemail.net) has been published on GitHub, or an existing release has been updated. This is a broadcast event sent to ALL connected clients, regardless of alias. The server polls GitHub every 15 minutes and uses a content-based fingerprint to detect changes. **Asset Gating**: The broadcast is deferred until release assets are available, preventing notifications for releases that are still building.", "required": [ "event", "timestamp", "release" ], "properties": { "event": { "type": "string", "enum": [ "newRelease" ] }, "timestamp": { "type": "integer", "description": "Unix timestamp in milliseconds when the event was emitted" }, "release": { "type": "object", "description": "The GitHub release object for the mail app", "required": [ "tagName", "name", "htmlUrl" ], "properties": { "tagName": { "type": "string", "description": "Git tag name of the release (e.g. \"v1.2.3\")" }, "name": { "type": "string", "description": "Release title" }, "body": { "type": "string", "description": "Release notes in Markdown format" }, "htmlUrl": { "type": "string", "format": "uri", "description": "URL to the release page on GitHub" }, "prerelease": { "type": "boolean", "description": "Whether this is a pre-release" }, "publishedAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of when the release was published" }, "author": { "type": "object", "description": "GitHub user who published the release", "properties": { "login": { "type": "string", "description": "GitHub username" }, "avatarUrl": { "type": "string", "format": "uri", "description": "URL to the user's avatar image" }, "htmlUrl": { "type": "string", "format": "uri", "description": "URL to the user's GitHub profile" } } }, "assets": { "type": "array", "description": "Downloadable assets attached to the release", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Asset file name" }, "size": { "type": "integer", "description": "Asset file size in bytes" }, "downloadCount": { "type": "integer", "description": "Number of times the asset has been downloaded" }, "browserDownloadUrl": { "type": "string", "format": "uri", "description": "Direct download URL for the asset" }, "contentType": { "type": "string", "description": "MIME type of the asset" } } } } } } }, "example": { "event": "newRelease", "timestamp": 1739348200000, "release": { "tagName": "v1.2.3", "name": "Release v1.2.3", "body": "This release includes several bug fixes and performance improvements.", "htmlUrl": "https://github.com/forwardemail/mail.forwardemail.net/releases/tag/v1.2.3", "prerelease": false, "publishedAt": "2026-02-15T12:00:00Z", "author": { "login": "niftylettuce", "avatarUrl": "https://avatars.githubusercontent.com/u/1127956", "htmlUrl": "https://github.com/niftylettuce" }, "assets": [ { "name": "mail.forwardemail.net-1.2.3.dmg", "size": 104857600, "downloadCount": 500, "browserDownloadUrl": "https://github.com/forwardemail/mail.forwardemail.net/releases/download/v1.2.3/mail.forwardemail.net-1.2.3.dmg", "contentType": "application/x-apple-diskimage" } ] } } } ], "discriminator": { "propertyName": "event" } } } } }, "400": { "description": "Bad Request - Missing or invalid authentication parameters" }, "401": { "description": "Unauthorized - Invalid API token or alias credentials. Note: authentication is optional; this error only occurs when credentials are provided but are invalid." }, "404": { "description": "Not Found - Alias not found for the provided credentials" }, "429": { "description": "Too Many Requests - Rate limit exceeded (30 connections/minute per IP)" }, "503": { "description": "Service Unavailable - Global connection limit reached" } }, "security": [ { "ApiKeyAuth": [] }, { "AliasAuth": [] }, {} ] } }, "/v1/domains/{domain_id}/allowlist": { "put": { "summary": "Update domain allowlist", "description": "Replace the allowlist for a domain. The allowlist restricts inbound mail to only the specified senders. Each entry must be a valid IP address, fully qualified domain name (FQDN), email address, or wildcard top-level domain (e.g. `*.com`). A maximum of 1000 entries is allowed. Wildcard public-suffix rules may contain multiple labels, for example `*.gov.co` and `*.gov.br`; they match senders under that exact suffix.", "operationId": "updateDomainAllowlist", "tags": [ "Domains" ], "parameters": [ { "name": "domain_id", "in": "path", "required": true, "description": "Fully qualified domain name (FQDN) or domain ID", "schema": { "type": "string" } } ], "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "allowlist": { "type": "array", "items": { "type": "string" }, "description": "Array of allowlisted senders (IP addresses, FQDNs, email addresses, or wildcard TLDs such as `*.com`). Pass an empty array to clear the allowlist. Wildcard public-suffix rules may contain multiple labels, for example `*.gov.co` and `*.gov.br`; they match senders under that exact suffix." } }, "required": [ "allowlist" ] } } } }, "responses": { "200": { "description": "Domain updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Domain" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/domains/{domain_id}/denylist": { "put": { "summary": "Update domain denylist", "description": "Replace the denylist for a domain. Mail from denylisted senders will be rejected. Each entry must be a valid IP address, fully qualified domain name (FQDN), email address, or wildcard top-level domain (e.g. `*.com`). A maximum of 1000 entries is allowed. Wildcard public-suffix rules may contain multiple labels, for example `*.gov.co` and `*.gov.br`; they match senders under that exact suffix.", "operationId": "updateDomainDenylist", "tags": [ "Domains" ], "parameters": [ { "name": "domain_id", "in": "path", "required": true, "description": "Fully qualified domain name (FQDN) or domain ID", "schema": { "type": "string" } } ], "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "denylist": { "type": "array", "items": { "type": "string" }, "description": "Array of denylisted senders (IP addresses, FQDNs, email addresses, or wildcard TLDs such as `*.com`). Pass an empty array to clear the denylist. Wildcard public-suffix rules may contain multiple labels, for example `*.gov.co` and `*.gov.br`; they match senders under that exact suffix." } }, "required": [ "denylist" ] } } } }, "responses": { "200": { "description": "Domain updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Domain" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/push-tokens": { "get": { "tags": [ "Push Tokens" ], "summary": "List push tokens", "description": "Retrieve all active (non-expired) push tokens for the authenticated alias. Supports optional platform filtering via query parameter.", "operationId": "listPushTokens", "security": [ { "AliasAuth": [] }, { "ApiKeyAuth": [] } ], "parameters": [ { "name": "platform", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "apns", "fcm", "unified-push", "web-push" ] }, "description": "Filter tokens by platform" }, { "name": "alias_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Required when using API token authentication" } ], "responses": { "200": { "description": "Push tokens retrieved successfully", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PushToken" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "post": { "tags": [ "Push Tokens" ], "summary": "Register push token", "description": "Register a new push token or refresh an existing one (upsert). If a token with the same (alias, platform, token) combination already exists, its expiry is extended and failure count is reset. Tokens are automatically pruned after 90 days of inactivity or 3 consecutive delivery failures.", "operationId": "createPushToken", "security": [ { "AliasAuth": [] }, { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PushTokenInput" } } } }, "responses": { "201": { "description": "Push token registered successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PushToken" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "delete": { "tags": [ "Push Tokens" ], "summary": "Remove all push tokens", "description": "Remove all push tokens for the authenticated alias. Useful for logout or account deletion flows.", "operationId": "removeAllPushTokens", "security": [ { "AliasAuth": [] }, { "ApiKeyAuth": [] } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "alias_id": { "type": "string", "description": "Required when using API token authentication" } } } } } }, "responses": { "200": { "description": "All push tokens removed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PushTokenDeletion" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v1/push-tokens/{id}": { "delete": { "tags": [ "Push Tokens" ], "summary": "Remove push token", "description": "Remove a specific push token by ID. Only the owning user/alias can delete their own tokens.", "operationId": "removePushToken", "security": [ { "AliasAuth": [] }, { "ApiKeyAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Push token document ID" } ], "responses": { "204": { "description": "Push token removed successfully" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } } }, "tags": [ { "name": "Account", "description": "Account management endpoints" }, { "name": "Logs", "description": "Log management endpoints" }, { "name": "Emails", "description": "Email management endpoints" }, { "name": "Domains", "description": "> [!TIP]\n> Domain endpoints with a domain's name /v1/domains/:domain\\_name as their endpoint are interchangeable with a domain's ID :domain\\_id. This means you can refer to the domain by either its name or id value." }, { "name": "Invites", "description": "Domain invite management endpoints" }, { "name": "Members", "description": "Domain member management endpoints" }, { "name": "Aliases", "description": "Domain alias management endpoints" }, { "name": "Encrypt", "description": "Encryption endpoints" }, { "name": "Contacts", "description": "Alias contacts management endpoints (CardDAV)\n\n>[!NOTE]\n>Unlike other API endpoints, these require Authentication \"username\" equal to the alias username and \"password\" equal to the alias generated password as Basic Authorization headers.\n\n>[!TIP]\n>These endpoints provide full CRUD operations for contact management with vCard support, including creation, retrieval, updating, and deletion of contacts. You can provide either vCard content directly or individual contact fields that will be converted to vCard format." }, { "name": "Calendars", "description": "Alias calendars management endpoints (CalDAV)\n\n>[!NOTE]\n> Unlike other API endpoints, these require [Authentication](#description/authentication) \"username\" equal to the alias username and \"password\" equal to the alias generated password as Basic Authorization headers.\n\n>[!TIP]\n> These endpoints provide complete calendar management with timezone and color support, including creation, retrieval, updating, and deletion of calendars. Calendar names are required, while other properties like color, timezone, and description are optional." }, { "name": "Calendar Events", "description": "Alias calendar events management endpoints (CalDAV)\n\n>[!NOTE]\n> Unlike other API endpoints, these require [Authentication](#description/authentication) \"username\" equal to the alias username and \"password\" equal to the alias generated password as Basic Authorization headers.\n\n>[!TIP]\n> These endpoints provide comprehensive calendar event management with full iCalendar (RFC 5545) support. Events are stored as iCal data and automatically parsed to extract common properties like summary, description, location, and dates for easy access. Events support soft deletion and can be filtered by calendar, date range, and deletion status." }, { "name": "Messages", "description": "Alias messages management endpoints (IMAP/POP3)\n\n>[!NOTE]\n> Unlike other API endpoints, these require [Authentication](#description/authentication) \"username\" equal to the alias username and \"password\" equal to the alias generated password as Basic Authorization headers.\n\n>[!TIP]\n> These endpoints provide comprehensive message management with advanced search capabilities. You can search by folder, flags, content, headers, date ranges, size, and more. Messages can be created using standard Nodemailer format and support moving between folders and flag management.\n\nPlease ensure that you have followed setup instructions for your domain.\nThese instructions can be found in our FAQ section [Do you support receiving email with IMAP?](/faq#do-you-support-receiving-email-with-imap)." }, { "name": "Folders", "description": "Alias folders management endpoints (IMAP/POP3)\n\n>[!TIP]\n> Folder endpoints with a folder's path /v1/folders/:path as their endpoint are interchangeable with a folder's ID :id. This means you can refer to the folder by either its path or id value.\n\n>[!NOTE]\n> Unlike other API endpoints, these require [Authentication](#description/authentication) \"username\" equal to the alias username and \"password\" equal to the alias generated password as Basic Authorization headers.\n\n>[!TIP]\n> These endpoints provide full folder management including creation, renaming, and deletion. Folder paths can include parent folders (e.g., 'INBOX/Subfolder'), and parent folders will be created automatically if they don't exist." }, { "name": "Sieve Scripts", "description": "Sieve script management endpoints\n\n>[!NOTE]\n> Sieve is a powerful email filtering language defined in RFC 5228. Scripts are executed on incoming mail to automatically organize, filter, and respond to messages.\n\n>[!TIP]\n> Supported extensions include: fileinto, reject, ereject, vacation, vacation-seconds, imap4flags, envelope, body, relational, comparator-i;ascii-numeric, copy, date, index, editheader, enotify, regex, subaddress, ihave, duplicate, special-use, mailbox, environment, and variables. Scripts are validated before saving to ensure they are syntactically correct.\n\n>[!NOTE]\n> **Two authentication methods are supported:**\n> - **API Token Auth** (`/v1/domains/{domain_id}/aliases/{alias_id}/sieve`): Use your API key as the username with Basic Auth. Requires domain_id and alias_id in the URL path.\n> - **Alias Auth** (`/v1/sieve-scripts`): Use the alias email and generated password as Basic Auth credentials. No domain_id or alias_id needed in the URL.\n\n>[!TIP]\n> Script ID parameters accept either the MongoDB ObjectId or the script name, allowing flexible script identification." }, { "name": "WebSockets", "description": "Real-time push notifications via WebSocket. Connect to the /v1/ws endpoint to receive live events. Authentication is optional: authenticated clients receive per-alias events (IMAP, CalDAV, CardDAV) and global broadcast events, while unauthenticated clients receive only global broadcast events (e.g. newRelease). Supports 20 distinct event types covering message delivery, moves, copies, flag changes, expunges, mailbox CRUD, calendar CRUD, calendar event CRUD, contact CRUD, address book CRUD, and app release broadcasts from the Forward Email Mail App (https://github.com/forwardemail/mail.forwardemail.net)." }, { "name": "Push Tokens", "description": "Register and manage push notification tokens for APNs, FCM, UnifiedPush, and Web Push. Tokens are scoped to an alias and used to deliver notifications when the app is backgrounded or closed." } ] }