Link Menu Expand (external link) Document Search Copy Copied
This website is for Zenphi public documentation.

Find User's Gmail Message (Raw)

Definition

The Find User’s Gmail Message (Raw) action allows administrators to retrieve the complete, unalterable content of a specific email from any user’s Gmail account within the organization.

Unlike standard retrieval actions that parse an email into simple “Subject,” “Body,” and “Attachments” fields, this action retrieves the Raw RFC 822 data. This means it fetches the exact data block that was received by the server, preserving all headers, routing information, security signatures, and formatting code.

Why use “Raw”? (RFC 822 Explained)

When you view an email in Gmail, you see a “Rendered” version—a pretty interface that hides the technical details. Raw (RFC 822) is the industry-standard format for email data. Using the Raw action provides three critical advantages:

  1. Forensic Integrity: It includes Trace Headers (IP addresses of passing servers) and Cryptographic Signatures (DKIM/SPF) required for legal proof and security investigations.
  2. Perfect Archiving: It bundles the body, HTML formatting, and all attachments into a single text block. Saving this as an .eml file ensures the email looks exactly the same 10 years from now as it does today.
  3. Portability: Files created from this raw data (.eml) can be opened by any email client (Outlook, Apple Mail, Thunderbird) without conversion.

Inputs

  1. Connection
    • Purpose: Establishes the link between Zenphi and your Google Workspace environment.
    • ️ Requirement: You must select a connection that has Domain-Wide Delegation enabled. A standard user-level Gmail connection will not work here, as you are accessing another user’s mailbox (e.g., an employee’s inbox) on their behalf.
  2. User Email
    • Purpose: Specifies the target mailbox (e.g., employee@company.com) that contains the email you wish to retrieve.
    • Practical Guidance: You can type a static email or use the Token Picker to map an email address from a previous step (e.g., from a “List Users” action or a “Security Alert” trigger).
  3. Message Id
    • Purpose: The unique identifier of the specific email you want to retrieve.
    • Practical Guidance: This is almost always a dynamic value. You typically use a List User’s Gmail Messages action first to find the email based on a search query (Subject, Date, etc.), then pass the Message ID from that list into this field.
  4. Return Raw Message as Plain Text
    • Purpose: Determines the format of the retrieved message payload.
    • Options:
    • False (Default): Returns a Base64url encoded string. Use this only if you are sending the data to an external API that specifically requires encoded input.
    • True (Recommended for Files): Returns the decoded Plain Text (EML format). Select this option if you intend to save the email as a .eml file to Google Drive.

Outputs

  1. Raw Message : You can map this output directly to the File Content input of a “Save File” (Google Drive) action to instantly archive the email.
  • Data Type: File Object
  • Description: This is the primary output. It is a structured file object containing the full email content.
  • Properties:
  • Name: Suggested filename (e.g., msg-{ID}.eml).
  • Mime Type: message/rfc822.
  • Content: The actual email data (Payload).
  1. Message Id / Thread Id / History Id
    • Unique identifiers for the message and its conversation thread.
  2. Internal Date
    • The timestamp (in milliseconds) indicating when the message was received by Google servers.
  3. Label IDs
    • A list of system tags (e.g., “INBOX”, “SENT”, “SPAM”, “URGENT”) currently applied to the message.
  4. Snippet
    • A short text preview of the email body. This is useful for logging or sending notifications to admins (e.g., “Archived email starting with: ‘Please find attached…’”).

Example Use Cases

  1. Preserve Evidence for Legal Discovery: Retrieve the raw RFC 822 format of specific emails to maintain forensic integrity for legal holds.
  2. Analyze Phishing Headers: Extract full message headers to investigate sender origins, routing paths, and potential spoofing attempts that are hidden in the standard view.
  3. Archive Emails as EML Files: Convert important communications into .eml files and save them to Google Drive for long-term retention outside of the Gmail ecosystem.
  4. Migrate Email Data: Pull raw message data to programmatically transfer emails between accounts or into a third-party CRM system while keeping original metadata intact.

Example Scenario: The Security Investigation

Goal: A security officer receives a report of a suspicious phishing email in an employee’s inbox (victim@company.com). To conduct a proper forensic investigation, the officer needs to extract the email in its original, unalterable state and save it as an .eml file in a secure Google Drive folder.

Steps to Implement:

  1. Trigger: Manual / On Demand (Initiated by the Security Officer).
  2. Action: List User’s Gmail Messages.
    • Connection: Workspace Admin.
    • User Email: victim@company.com
    • Search Query: subject:"Urgent Wire Transfer" is:unread
    • Output: This finds the specific email and provides its Message ID.
  3. Action: Find User’s Gmail Message (Raw).
    • Connection: Workspace Admin (Domain-Wide).
    • User Email: victim@company.com
    • Message Id: Map the Message ID from the previous step.
    • Return Raw Message as Plain Text: True (Crucial for creating a readable file).
  4. Action: Google Drive - Save File.
    • File Content: Map the Raw Message object from the previous step.
    • File Name: Map the Raw Message > Name (e.g., suspicious_email.eml).
    • Folder: Select the secure “Security Investigations” folder.

Outcome: The workflow retrieves the complete raw data of the suspicious email. It automatically generates an .eml file and saves it to a secure folder. The security team can now open this file in any text editor or email client to inspect the routing headers and verify the sender’s authenticity without alerting the sender or altering the evidence.

Best Practices

  1. Always Enable “Plain Text” for Files: If your goal is to save the email or view it, you must set “Return Raw Message as Plain Text” to True. Leaving it as False (Base64) will result in a file filled with unreadable random characters.
  2. Pair with Search Actions: Since this action requires a precise Message Id, it is standard practice to precede it with a List User’s Gmail Messages action. Do not try to guess IDs; always look them up dynamically.
  3. Secure Sensitive Data: The output of this action contains the entire email payload, including attachments and private headers. Ensure that any logs or Google Drive folders used in subsequent steps have strict access controls.
  4. Verify Permissions: Ensure your connection has the necessary Domain-Wide Delegation. Without this, the action will fail with “Unauthorized” errors because you are attempting to access a mailbox that does not belong to the admin user directly.