Skip to main content
Outbound emails let you send emails through connected Gmail accounts while maintaining a complete audit trail. Every email you send is tracked from creation through delivery, with automatic correlation to incoming replies and bounce notifications.

​
Why Outbound Emails?

When you send an email via the Gmail API, the response only includes a message ID. The full email content (with headers, threading info, etc.) arrives asynchronously via Gmail’s push notifications. The OutboundEmail model bridges this gap by:
  1. Recording intent immediately - Before calling Gmail, we store what you’re sending
  2. Correlating responses - When Gmail syncs the sent message, we link it back
  3. Tracking deliverability - Bounce notifications are automatically detected and associated

​
Lifecycle States

StatusDescription
DRAFTEmail is being composed. Can be edited or scheduled with planned_send_at.
PENDINGSend has been initiated but Gmail hasn’t confirmed yet.
SENTGmail accepted the message. provider_message_id and provider_thread_id are populated.
FAILEDGmail rejected the send. Check error_message for details.

​
Correlation & Tracking

When an email is sent successfully, we capture:
  • provider_message_id - Gmail’s unique message ID (used to match the async EmailMessage record)
  • provider_thread_id - Gmail’s thread ID (for conversation threading)
  • message_id_header - The RFC 2822 Message-ID header (used for bounce correlation)
When Gmail’s push notification syncs the sent message, the system automatically associates the EmailMessage record with the OutboundEmail via email_message_uid.

​
Bounce Detection

Delivery failures (bounces) are detected automatically when syncing emails:
  1. Detection - Messages from MAILER-DAEMON or with multipart/report content type are identified as DSN (Delivery Status Notification) messages
  2. Correlation - The original message is found using the In-Reply-To header or message_id_header matching
  3. Update - The OutboundEmail record is updated with:
    • delivery_status = "bounce_detected"
    • bounce_details containing recipient, status code, and diagnostic message
{
  "delivery_status": "bounce_detected",
  "bounce_details": {
    "bounced_recipients": [
      {
        "email": "invalid@example.com",
        "action": "failed",
        "status_code": "5.1.1",
        "diagnostic": "smtp; 550 5.1.1 User unknown"
      }
    ],
    "detected_at": "2024-03-25T10:30:00Z"
  }
}

​
Context Linking

Outbound emails can be linked to domain entities (like invoices) using:
  • context_type - The entity type (e.g., "invoice")
  • context_id - The entity’s UUID
This enables filtering emails by context and provides rich data for AI-powered content generation.