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

Insert Gmail Message (Raw)

Definition

The Insert Gmail Message (Raw) action allows you to directly inject a raw email message (in RFC 822 format) into a specific user’s Gmail mailbox.

Unlike sending an email through standard delivery channels (SMTP), this action acts like an IMAP APPEND operation. It places the message directly into the message store without triggering inbound scanning, spam filters, or “New Email” notifications.

Key capabilities include:

  • Migration & Restoration: Inserting fully formatted raw emails while bypassing delivery routing.
  • Timestamp Preservation: Preserving the original email timestamp (e.g., inserting an email today that appears in the mailbox dated 2020).
  • Labeling: Applying specific labels (such as INBOX, SENT, or MIGRATED) immediately upon insertion.

This action is essential for automation workflows involving email migration, archival restoration, or consolidating mailboxes.

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 modifying another user’s mailbox.
  2. User Email
    • Purpose: Specifies the target mailbox (e.g., manager@company.com) where the message will be inserted.
    • Practical Guidance: Use the Token Picker to map the email address of the destination user.
  3. Raw RFC 822 Message
    • Purpose: The full content of the email, including headers and body.
    • Practical Guidance: This is typically a dynamic token mapped from a previous “Find User’s Gmail Message (Raw)” action. You are essentially taking the “blob” of data from one email and pasting it here.
  4. Raw Is Base64URL Encoded
    • Purpose: Tells Zenphi how to interpret the data in the “Raw RFC 822 Message” field.
    • Configuration Strategy:
    • Select True: If your source data is a Base64 string (e.g., you used “Find Raw” with ‘Return Plain Text’ = False).
    • Select False: If your source data is Plain Text (e.g., you used “Find Raw” with ‘Return Plain Text’ = True, or you constructed the text manually).
  • Why it matters: Mismatched encoding will result in the email body appearing as a block of random gibberish characters.
  1. Label IDs
    • Purpose: Assigns specific labels (folders) to the message at the moment it is inserted.
    • Crucial Tip: By default, inserted messages go to “All Mail”. You must add the label INBOX (case-sensitive) if you want the email to appear in the user’s main inbox.
    • Other Examples: SENT, STARRED, TRASH.
  2. Use Message Date Header
    • Purpose: Determines the timestamp shown in Gmail.
    • Options:
    • True (Recommended for Migration): Uses the date found inside the email headers. The email will be sorted chronologically (e.g., appearing back in 2022).
    • False: Uses the current time of insertion. The email will appear as “0 minutes ago” at the top of the inbox.

Outputs

  1. Message Id
    • The immutable, unique identifier assigned to the new message by Google.
  2. Thread Id
    • The identifier for the conversation thread to which this message belongs.
  3. Label Ids
    • A list of all label IDs that were successfully applied.

Example Use Cases

  1. Migrate Employee Data: Transfer emails from a departing employee’s account to a manager’s mailbox while preserving original timestamps and sender details.
  2. Restore Deleted Emails: Recover accidentally deleted messages from a backup archive (.eml files) and re-insert them directly into the user’s inbox.
  3. Consolidate Mailboxes: Merge email history from multiple legacy accounts into a single active Google Workspace account.
  4. Populate Audit Mailboxes: Inject specific emails flagged for legal review into a compliance officer’s mailbox without triggering new email notifications.

Example Scenario: The Handover

Goal: An employee (leaver@company.com) has left. You need to copy their “Project Alpha” emails into the manager’s inbox (manager@company.com). The emails must appear in the manager’s inbox exactly as they were, maintaining the original dates from last year.

Steps to Implement:

  1. Trigger: Manual / On Demand.
  2. Action: List User’s Gmail Messages.
    • User: leaver@company.com
    • Query: subject:"Project Alpha"
  3. Action: For Each Item (Loop).
  4. Action (Inside Loop): Find User’s Gmail Message (Raw).
    • User: leaver@company.com
    • Message Id: Map ID from loop.
    • Return Plain Text: False (We want the Base64 blob).
  5. Action (Inside Loop): Insert Gmail Message (Raw).
    • Connection: Workspace Admin.
    • User Email: manager@company.com
    • Raw RFC 822 Message: Map the Raw Message Content from the previous step.
    • Raw Is Base64URL Encoded: True (Matching the output of the previous step).
    • Label IDs: Add Item -> INBOX.
    • Use Message Date Header: True (To keep the original dates).

Outcome: The manager opens their inbox and sees the “Project Alpha” emails nestled correctly in their timeline from last year. They look identical to the originals, preserving the sender and history.

Best Practices

  1. Always Add the ‘INBOX’ Label: If you forget to add the INBOX label ID, the email will be inserted successfully but will be “archived” (hidden in All Mail). The user won’t see it unless they search for it.
  2. Match Your Encoding: This is the #1 cause of failure.
    • Source = Base64? Input setting = True.
    • Source = Text? Input setting = False.
  3. Preserve Timestamps: Always set Use Message Date Header to True for migrations. Otherwise, the manager will be flooded with 500 “New” emails all dated today, destroying the chronological context of the conversation.
  4. Batching: If inserting thousands of emails, use a standard “Delay” action (e.g., 1 second per email) inside your loop to avoid hitting Google’s API rate limits (approx. 1 request per second per user).