anil.recoil.org / slop
My agentic slop goes here. Not intended for anyone else!
fork atom
slop / jmap / docs / queries / 08-vacation-response-status.md
at jsont 11 kB view raw view code

Query 8: Current Vacation Response Status and Configuration#

Use Case Description#

Check the current vacation response (out-of-office) configuration and recent auto-reply activity. This demonstrates VacationResponse singleton object handling and integration with email submission tracking.

Key JMAP Concepts Used#

  • Singleton objects: VacationResponse with fixed ID "singleton"
  • VacationResponse/get: Retrieving auto-reply configuration
  • Date range validation: Checking if vacation period is active
  • EmailSubmission correlation: Finding auto-sent vacation replies
  • Auto-reply tracking: Monitoring system-generated responses

JMAP Request#

{
  "using": ["urn:ietf:params:jmap:core", "urn:ietf:params:jmap:mail"],
  "methodCalls": [
    [
      "VacationResponse/get",
      {
        "accountId": "u12345678",
        "ids": ["singleton"]
      },
      "vr0"
    ],
    [
      "EmailSubmission/query",
      {
        "accountId": "u12345678", 
        "filter": {
          "operator": "AND",
          "conditions": [
            {
              "hasKeyword": "$autosent"
            },
            {
              "after": "2024-08-20T00:00:00Z"
            }
          ]
        },
        "sort": [
          {
            "property": "created", 
            "isAscending": false
          }
        ],
        "limit": 10
      },
      "sub0"
    ],
    [
      "EmailSubmission/get",
      {
        "accountId": "u12345678",
        "#ids": {
          "resultOf": "sub0",
          "name": "EmailSubmission/query",
          "path": "/ids"
        },
        "properties": [
          "id", "emailId", "identityId", "envelope", "created",
          "deliveryStatus", "submissionId"
        ]
      },
      "subg0"
    ],
    [
      "Email/get",
      {
        "accountId": "u12345678",
        "#ids": {
          "resultOf": "subg0", 
          "name": "EmailSubmission/get",
          "path": "/list/*/emailId"
        },
        "properties": [
          "id", "subject", "preview", "from", "to", "sentAt", "keywords",
          "textBody", "bodyValues"
        ],
        "bodyProperties": ["value", "isEncodingProblem", "isTruncated"]
      },
      "eg0"
    ]
  ]
}

Expected Response Structure#

{
  "methodResponses": [
    [
      "VacationResponse/get",
      {
        "accountId": "u12345678",
        "state": "vr9876543217",
        "list": [
          {
            "id": "singleton",
            "isEnabled": true,
            "fromDate": "2024-08-20T00:00:00Z",
            "toDate": "2024-08-30T23:59:59Z",
            "subject": "Out of Office - Returning August 31st", 
            "textBody": "Thank you for your email. I am currently out of the office on vacation from August 20-30, 2024.\n\nFor urgent matters, please contact my colleague Sarah at sarah@example.com or call the main office at (555) 123-4567.\n\nI will respond to your message when I return on August 31st.\n\nBest regards,\nJohn Doe",
            "htmlBody": "<p>Thank you for your email. I am currently out of the office on vacation from <strong>August 20-30, 2024</strong>.</p><p>For urgent matters, please contact my colleague <a href=\"mailto:sarah@example.com\">Sarah</a> or call the main office at <strong>(555) 123-4567</strong>.</p><p>I will respond to your message when I return on <strong>August 31st</strong>.</p><p>Best regards,<br>John Doe</p>"
          }
        ],
        "notFound": []
      },
      "vr0"
    ],
    [
      "EmailSubmission/query", 
      {
        "accountId": "u12345678",
        "queryState": "sq1234567896",
        "canCalculateChanges": true,
        "position": 0,
        "ids": ["ES201", "ES202", "ES203", "ES204"],
        "total": 15,
        "limit": 10
      },
      "sub0"
    ],
    [
      "EmailSubmission/get",
      {
        "accountId": "u12345678", 
        "state": "s9876543217",
        "list": [
          {
            "id": "ES201",
            "emailId": "Memail501",
            "identityId": "I1",
            "envelope": {
              "mailFrom": "john.doe@example.com",
              "rcptTo": ["client@external.com"]
            },
            "created": "2024-08-24T10:15:00Z",
            "deliveryStatus": {
              "client@external.com": "delivered"
            },
            "submissionId": "auto-vacation-001"
          },
          {
            "id": "ES202",
            "emailId": "Memail502", 
            "identityId": "I1",
            "envelope": {
              "mailFrom": "john.doe@example.com",
              "rcptTo": ["colleague@partner.com"]
            },
            "created": "2024-08-23T14:30:00Z",
            "deliveryStatus": {
              "colleague@partner.com": "delivered"
            },
            "submissionId": "auto-vacation-002"
          }
        ],
        "notFound": []
      },
      "subg0"
    ],
    [
      "Email/get",
      {
        "accountId": "u12345678",
        "state": "s9876543217",
        "list": [
          {
            "id": "Memail501", 
            "subject": "Out of Office - Returning August 31st",
            "preview": "Thank you for your email. I am currently out of the office on vacation...",
            "from": [{"email": "john.doe@example.com", "name": "John Doe"}],
            "to": [{"email": "client@external.com", "name": "External Client"}],
            "sentAt": "2024-08-24T10:15:00Z",
            "keywords": {
              "$autosent": true,
              "$vacation": true
            },
            "textBody": [{"id": "vacation1", "mimeType": "text/plain"}],
            "bodyValues": {
              "vacation1": {
                "value": "Thank you for your email. I am currently out of the office on vacation from August 20-30, 2024.\n\nFor urgent matters, please contact my colleague Sarah at sarah@example.com or call the main office at (555) 123-4567.\n\nI will respond to your message when I return on August 31st.\n\nBest regards,\nJohn Doe",
                "isEncodingProblem": false,
                "isTruncated": false
              }
            }
          },
          {
            "id": "Memail502",
            "subject": "Out of Office - Returning August 31st",
            "preview": "Thank you for your email. I am currently out of the office on vacation...",
            "from": [{"email": "john.doe@example.com", "name": "John Doe"}],
            "to": [{"email": "colleague@partner.com", "name": "Business Partner"}],
            "sentAt": "2024-08-23T14:30:00Z",
            "keywords": {
              "$autosent": true,
              "$vacation": true
            },
            "textBody": [{"id": "vacation2", "mimeType": "text/plain"}],
            "bodyValues": {
              "vacation2": {
                "value": "Thank you for your email. I am currently out of the office on vacation from August 20-30, 2024.\n\nFor urgent matters, please contact my colleague Sarah at sarah@example.com or call the main office at (555) 123-4567.\n\nI will respond to your message when I return on August 31st.\n\nBest regards,\nJohn Doe",
                "isEncodingProblem": false,
                "isTruncated": false
              }
            }
          }
        ],
        "notFound": []
      },
      "eg0"
    ]
  ]
}

Explanation of Key Features#

VacationResponse Singleton Pattern#

  • Fixed ID: VacationResponse always uses ID "singleton"
  • Account-wide: Only one vacation response configuration per account
  • Date-controlled: fromDate and toDate define active period
  • Multi-format: Both textBody and htmlBody for different email clients

Vacation Response Configuration Analysis#

{
  "isEnabled": true,
  "fromDate": "2024-08-20T00:00:00Z", 
  "toDate": "2024-08-30T23:59:59Z",
  "subject": "Out of Office - Returning August 31st"
}

Status Validation:

  • Check if current date falls within fromDate to toDate range
  • isEnabled: true confirms auto-replies are active
  • Custom subject line overrides default "Out of Office" message

Auto-Reply Tracking#

  • $autosent keyword: Identifies system-generated emails
  • EmailSubmission records: Track delivery status of auto-replies
  • submissionId: Unique identifier for vacation response submissions
  • Delivery confirmation: Verify vacation messages were delivered

Vacation Response Content Structure#

{
  "textBody": "Plain text version for simple email clients",
  "htmlBody": "<p>Rich HTML version with <strong>formatting</strong> and <a href=\"mailto:sarah@example.com\">links</a></p>"
}

Auto-Reply Frequency Control#

JMAP servers typically implement:

  • Per-sender limits: One auto-reply per sender per vacation period
  • Duplicate detection: Avoid reply loops with other auto-responders
  • Timeouts: Minimum intervals between replies to same sender
  • Exemption lists: Skip auto-replies for certain senders (internal, mailing lists)

Vacation Response Management Queries#

Check Active Status:

// Client-side logic to determine if vacation is currently active
const now = new Date().toISOString();
const isActive = vacationResponse.isEnabled && 
                 vacationResponse.fromDate <= now && 
                 now <= vacationResponse.toDate;

Recent Auto-Reply Statistics:

{
  "filter": {
    "operator": "AND",
    "conditions": [
      {"hasKeyword": "$autosent"},
      {"hasKeyword": "$vacation"},
      {"after": "2024-08-20T00:00:00Z"}
    ]
  }
}

Failed Auto-Replies:

{
  "filter": {
    "operator": "AND", 
    "conditions": [
      {"hasKeyword": "$autosent"},
      {"deliveryStatus": "failed"}
    ]
  }
}

Business Logic Applications#

Vacation Management Workflow:

  1. Pre-vacation setup: Configure dates, message content, backup contacts
  2. Activation monitoring: Verify auto-replies start sending on fromDate
  3. Activity tracking: Monitor delivery success rates and recipient feedback
  4. Return preparation: Disable before return date to avoid late responses

Administrative Oversight:

  • Track which employees have active vacation responses
  • Monitor auto-reply volume and server resource usage
  • Ensure compliance with email policies and professional standards
  • Generate vacation coverage reports for management

Integration with Calendar Systems:

  • Sync vacation dates with calendar appointments
  • Automatically enable/disable based on calendar events
  • Coordinate with meeting scheduling systems
  • Update presence status in communication platforms

Error Handling and Edge Cases#

  • Timezone considerations: Use UTC dates for consistent behavior
  • Date validation: Ensure fromDate < toDate
  • Content validation: Check for required elements (return date, contact info)
  • Delivery failures: Monitor and alert on auto-reply delivery issues
  • Reply loop prevention: Detect and break auto-responder chains