Use cases → Email operations
Implementing after-hours auto-response with domain-wide delegation
Set up an after-hours auto-responder using a delegated service account, with advice on handling Gmail API quirks and confidential message edge cases.
| Who it is for | Workspace automation engineers managing out-of-hours communications for multiple users. |
|---|---|
| APIs | Gmail API |
| Typical scopes | gmail.send, gmail.readonly |
The problem
Many organisations want to automatically reply to emails received outside business hours, but Gmail's built-in vacation responder is per-user and lacks custom logic. Using a delegated service account enables centralised, scriptable responses, but introduces Gmail API propagation delays and edge cases not seen with user-level solutions. Without careful handling, the auto-responder can miss new messages, send duplicate replies, or fail silently on certain message types.
How it works
- Create a service account and configure domain-wide delegation with 'gmail.readonly' and 'gmail.send' scopes.
- Poll 'users.messages.list' with 'q=label:inbox is:unread' every 1-5 minutes, filtering results by 'internalDate' to only process new mail since the last poll.
- For each new message, check if it already has a custom label (e.g. 'auto-replied') or if its threadId is in a persistent log to avoid duplicate replies.
- Send an auto-reply using 'users.messages.send', referencing the original thread.
- Apply a label (via 'users.messages.modify') or update your log to mark the message as replied.
- Explicitly log and skip confidential mode messages, as they cannot be read or replied to.
What changes
You gain centralised control over auto-responses for the whole domain, with customisable logic and logging. Unlike Gmail's built-in responder, this approach can adapt to business rules but requires handling Google API edge cases.
Watch it explained
“Create Google API Key (2024) || Google Cloud Platform *NEW*” — Code & Code on YouTube. Third-party video, included because it covers this ground well. We are not affiliated with the channel.
Questions people ask
How does this differ from using Gmail's vacation responder?
The delegated service account approach allows for custom logic, centralised logging, and multi-user management, but you must handle API delays and message filtering logic yourself. Gmail's built-in responder is simpler but cannot be centrally managed or customised.
How can I avoid sending duplicate auto-replies to the same thread?
Track replied threadIds in a persistent store, or apply a custom label to each message after replying. Always check for this marker before sending a reply.
Why do some messages never get an auto-response?
Confidential mode messages are inaccessible to service accounts, and API propagation delays can cause new mail to appear late. Always log skipped messages and consider a secondary check on older mail.
Want this built?
This is a pattern we run in production. We will set up the delegation and build this on top of it — $500 per hour, most of it working the same day.
Talk to us Or read the setup guideRelated use cases
Draft replies automatically in a shared inbox
A delegated service account reads an incoming enquiry, drafts a researched reply in the mailbox, and leaves it for a human to approve and send.
Triage and route inbound mail across a domain
Classify every inbound message, label it, and forward the ones that matter to the person who owns them — without touching a single mail rule.
Send mail as a shared alias from automation
Deliver notifications, confirmations and campaign replies from a branded address like support@ or updates@ without a human in the loop.