Repository navigation
Conversation
`config.action_mailer.delivery_method = :posthog` sends each mail as one PostHog email through the client PostHog.init made, for deliver_now and deliver_later. The delivery method registers in Action Mailer's load hook, so apps without Action Mailer load none of it. Each mail maps to one send or a named refusal before any request: one To address, bare recipient addresses, the From display name, HTML and text bodies, attachments with inline content IDs, and the reserved X-PostHog-* headers for the send options, which never go out. Mail is named <mailer>-<action> unless it sets a template key. Refusals raise PostHog::Rails::UnsupportedMailError and failed sends PostHog::Rails::DeliveryError with retryable?, both honouring raise_delivery_errors. Every send carries X-PostHog-Integration: action-mailer/<posthog-rails version>. Ticket: PostHog/michaelr-context#43 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
posthog-ruby-sync Compliance ReportDate: 2026-11-13T07:34:07.451014+00:00
|
| Test | Status | Duration |
|---|---|---|
| Format Validation.Event Has Required Fields | ✅ | 10ms |
| Format Validation.Event Has Uuid | ✅ | 7ms |
| Format Validation.Event Has Lib Properties | ✅ | 7ms |
| Format Validation.Distinct Id Is String | ✅ | 9ms |
| Format Validation.Token Is Present | ✅ | 7ms |
| Format Validation.Custom Properties Preserved | ✅ | 8ms |
| Format Validation.Event Has Timestamp | ✅ | 8ms |
| Format Validation.Non Utc Event Timestamp Is Converted To Utc | ✅ | 8ms |
| Retry Behavior.Retries On 503 | ✅ | 5326ms |
| Retry Behavior.Does Not Retry On 400 | ❌ | 7ms |
| Retry Behavior.Does Not Retry On 401 | ❌ | 5ms |
| Retry Behavior.Respects Retry After Header | ✅ | 8017ms |
| Retry Behavior.Implements Backoff | ❌ | 252ms |
| Retry Behavior.Retries On 500 | ✅ | 5144ms |
| Retry Behavior.Retries On 502 | ✅ | 5148ms |
| Retry Behavior.Retries On 504 | ✅ | 5168ms |
| Retry Behavior.Max Retries Respected | ❌ | 560ms |
| Deduplication.Generates Unique Uuids | ✅ | 18ms |
| Deduplication.Preserves Uuid On Retry | ✅ | 5113ms |
| Deduplication.Preserves Uuid And Timestamp On Retry | ✅ | 10332ms |
| Deduplication.Preserves Uuid And Timestamp On Batch Retry | ✅ | 5122ms |
| Deduplication.No Duplicate Events In Batch | ✅ | 18ms |
| Deduplication.Different Events Have Different Uuids | ✅ | 10ms |
| Compression.Sends Gzip When Enabled | ✅ | 7ms |
| Batch Format.Uses Proper Batch Structure | ✅ | 6ms |
| Batch Format.Flush With No Events Sends Nothing | ✅ | 3ms |
| Batch Format.Multiple Events Batched Together | ❌ | 18ms |
| Error Handling.Does Not Retry On 403 | ❌ | 5ms |
| Error Handling.Does Not Retry On 413 | ❌ | 5ms |
| Error Handling.Retries On 408 | ✅ | 5115ms |
Failures
retry_behavior.does_not_retry_on_400
500, message='Internal Server Error', url='http://sdk-adapter:8080/capture'
retry_behavior.does_not_retry_on_401
500, message='Internal Server Error', url='http://sdk-adapter:8080/capture'
retry_behavior.implements_backoff
500, message='Internal Server Error', url='http://sdk-adapter:8080/capture'
retry_behavior.max_retries_respected
500, message='Internal Server Error', url='http://sdk-adapter:8080/capture'
batch_format.multiple_events_batched_together
Expected 1 requests, got 5
error_handling.does_not_retry_on_403
500, message='Internal Server Error', url='http://sdk-adapter:8080/capture'
error_handling.does_not_retry_on_413
500, message='Internal Server Error', url='http://sdk-adapter:8080/capture'
Feature_Flags Tests
View Details
| Test | Status | Duration |
|---|---|---|
| Request Payload.Request With Person Properties Device Id | ✅ | 9ms |
| Request Payload.Flags Request Uses V2 Query Param | ✅ | 9ms |
| Request Payload.Flags Request Hits Flags Path Not Decide | ✅ | 8ms |
| Request Payload.Flags Request Omits Authorization Header | ✅ | 8ms |
| Request Payload.Token In Flags Body Matches Init | ✅ | 7ms |
| Request Payload.Groups Round Trip | ✅ | 7ms |
| Request Payload.Groups Default To Empty Object | ✅ | 6ms |
| Request Payload.Disable Geoip False Propagates As Geoip Disable False | ✅ | 7ms |
| Request Payload.Disable Geoip Omitted Defaults To False | ❌ | 7ms |
| Request Payload.Flag Keys To Evaluate Contains Only Requested Key | ✅ | 6ms |
| Request Lifecycle.No Flags Request On Init Alone | ✅ | 2ms |
| Request Lifecycle.No Flags Request On Normal Capture | ✅ | 7ms |
| Request Lifecycle.Two Flag Calls Produce Two Remote Requests | ✅ | 9ms |
| Request Lifecycle.Mock Response Value Is Returned To Caller | ✅ | 6ms |
| Retry Behavior.Retries Flags On 502 | ✅ | 110ms |
| Retry Behavior.Retries Flags On 504 | ✅ | 111ms |
| Side Effect Events.Get Feature Flag Captures Feature Flag Called Event | ✅ | 10ms |
Failures
request_payload.disable_geoip_omitted_defaults_to_false
Field 'geoip_disable' not found in /flags request body at path 'geoip_disable'. Available keys: ['distinct_id', 'groups', 'person_properties', 'group_properties', 'flag_keys_to_evaluate', 'token']
posthog-ruby-async Compliance ReportDate: 2026-11-13T07:34:46.661443+00:00
|
| Test | Status | Duration |
|---|---|---|
| Format Validation.Event Has Required Fields | ✅ | 107ms |
| Format Validation.Event Has Uuid | ✅ | 106ms |
| Format Validation.Event Has Lib Properties | ✅ | 107ms |
| Format Validation.Distinct Id Is String | ✅ | 105ms |
| Format Validation.Token Is Present | ✅ | 106ms |
| Format Validation.Custom Properties Preserved | ✅ | 106ms |
| Format Validation.Event Has Timestamp | ✅ | 106ms |
| Format Validation.Non Utc Event Timestamp Is Converted To Utc | ✅ | 8ms |
| Retry Behavior.Retries On 503 | ✅ | 5310ms |
| Retry Behavior.Does Not Retry On 400 | ✅ | 2107ms |
| Retry Behavior.Does Not Retry On 401 | ✅ | 2108ms |
| Retry Behavior.Respects Retry After Header | ✅ | 8013ms |
| Retry Behavior.Implements Backoff | ✅ | 15722ms |
| Retry Behavior.Retries On 500 | ✅ | 5210ms |
| Retry Behavior.Retries On 502 | ✅ | 5209ms |
| Retry Behavior.Retries On 504 | ✅ | 5212ms |
| Retry Behavior.Max Retries Respected | ✅ | 15622ms |
| Deduplication.Generates Unique Uuids | ✅ | 109ms |
| Deduplication.Preserves Uuid On Retry | ✅ | 5210ms |
| Deduplication.Preserves Uuid And Timestamp On Retry | ✅ | 10416ms |
| Deduplication.Preserves Uuid And Timestamp On Batch Retry | ✅ | 5213ms |
| Deduplication.No Duplicate Events In Batch | ✅ | 110ms |
| Deduplication.Different Events Have Different Uuids | ✅ | 106ms |
| Compression.Sends Gzip When Enabled | ✅ | 105ms |
| Batch Format.Uses Proper Batch Structure | ✅ | 105ms |
| Batch Format.Flush With No Events Sends Nothing | ✅ | 4ms |
| Batch Format.Multiple Events Batched Together | ✅ | 110ms |
| Error Handling.Does Not Retry On 403 | ✅ | 2108ms |
| Error Handling.Does Not Retry On 413 | ✅ | 2109ms |
| Error Handling.Retries On 408 | ✅ | 5208ms |
Feature_Flags Tests
View Details
| Test | Status | Duration |
|---|---|---|
| Request Payload.Request With Person Properties Device Id | ✅ | 107ms |
| Request Payload.Flags Request Uses V2 Query Param | ✅ | 106ms |
| Request Payload.Flags Request Hits Flags Path Not Decide | ✅ | 106ms |
| Request Payload.Flags Request Omits Authorization Header | ✅ | 105ms |
| Request Payload.Token In Flags Body Matches Init | ✅ | 106ms |
| Request Payload.Groups Round Trip | ✅ | 106ms |
| Request Payload.Groups Default To Empty Object | ✅ | 106ms |
| Request Payload.Disable Geoip False Propagates As Geoip Disable False | ✅ | 106ms |
| Request Payload.Disable Geoip Omitted Defaults To False | ❌ | 106ms |
| Request Payload.Flag Keys To Evaluate Contains Only Requested Key | ✅ | 105ms |
| Request Lifecycle.No Flags Request On Init Alone | ✅ | 3ms |
| Request Lifecycle.No Flags Request On Normal Capture | ✅ | 104ms |
| Request Lifecycle.Two Flag Calls Produce Two Remote Requests | ✅ | 109ms |
| Request Lifecycle.Mock Response Value Is Returned To Caller | ✅ | 105ms |
| Retry Behavior.Retries Flags On 502 | ✅ | 249ms |
| Retry Behavior.Retries Flags On 504 | ✅ | 210ms |
| Side Effect Events.Get Feature Flag Captures Feature Flag Called Event | ✅ | 108ms |
Failures
request_payload.disable_geoip_omitted_defaults_to_false
Field 'geoip_disable' not found in /flags request body at path 'geoip_disable'. Available keys: ['distinct_id', 'groups', 'person_properties', 'group_properties', 'flag_keys_to_evaluate', 'token']
There was a problem hiding this comment.
PostHog Review · Standard · reviewed 9449b6e: 2 Should fix.
See this review and its findings in PostHog Review. Comment @posthog review --deep for a Deep review. A Deep review takes longer and looks deeper than a Standard review.
Keep the quotes a From display name needs, such as "Doe, Jane" <jane@example.com>, by formatting the address with Mail. Walk only multipart/mixed, alternative and related containers, and refuse any other multipart part, such as a signed message or a multipart attachment, with unsupported_part. Ignore only Content-Type and Content-Transfer-Encoding at the top level, so a header such as Content-Language is refused instead of dropped. Ticket: PostHog/michaelr-context#43 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Refuse a body part header PostHog can't carry, and an attachment that has no filename. Send an inline attachment's Content-ID as written. Refs PostHog/michaelr-context#43 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
There was a problem hiding this comment.
PostHog Review · Standard · reviewed c0507e2: 1 Should fix.
This is review round 3 on this pull request. When findings keep coming back in the same code, the approach is usually the problem. Before the next fix, check whether a different design would remove the whole class of findings.
PostHog takes an attachment's MIME type alone. Send the UTF-8 that Mail writes, and refuse any other charset. Refs PostHog/michaelr-context#43 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
There was a problem hiding this comment.
PostHog Review · Standard · reviewed e14111d: 1 Should fix.
This is review round 4 on this pull request. When findings keep coming back in the same code, the approach is usually the problem. Before the next fix, check whether a different design would remove the whole class of findings.
PostHog sends a body or an attachment by its MIME type. A body keeps only charset, and an attachment only charset, name, and filename. Refs PostHog/michaelr-context#43 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Refs PostHog/michaelr-context#43 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
There was a problem hiding this comment.
PostHog Review · Standard · reviewed 97588f8: 2 Should fix.
This is review round 5 on this pull request. When findings keep coming back in the same code, the approach is usually the problem. Before the next fix, check whether a different design would remove the whole class of findings.
|
|
||
| # Mail's own attachment? looks for a filename, but a Content-Disposition of attachment needs none. | ||
| def attached?(part) | ||
| part.attachment? || part.content_disposition.to_s.downcase.start_with?('attachment') |
There was a problem hiding this comment.
P2 · Classify inline resources before mapping them as bodies
For a related HTML message with a filename-less inline text/plain resource, Mail's attachment? and this predicate return false. content sends the resource as the plain-text body and drops its Content-ID, breaking the HTML's cid: reference instead of refusing the mail. Recognize inline resources during classification so the filename check runs.
There was a problem hiding this comment.
Fixed in 7e3b6bf: a part with a Content-ID is a resource the HTML refers to, never a body, so one without a filename is refused with unsupported_part before any request. Test: "refuses an inline resource without a filename instead of sending it as a body". A body part marked inline without a Content-ID still goes out as a body.
| refuse('unsupported_part', "PostHog can't send the #{part.charset} charset of #{part.filename}") | ||
| end | ||
| file = { filename: part.filename, content_type: part.mime_type, content: part.body.decoded.b } | ||
| return file unless part.inline? |
There was a problem hiding this comment.
P2 · Preserve Content-ID on related resources without inline disposition
A multipart/related image with a filename and Content-ID but no Content-Disposition is a valid CID resource. Mail's inline? returns false, so attachment sends its bytes without content_id, leaving the HTML's reference unresolved. Preserve the identifier for related resources regardless of disposition, or refuse content the API cannot preserve.
There was a problem hiding this comment.
Fixed in 7e3b6bf: the mapper sends a resource's Content-ID whenever the part has one, whatever its Content-Disposition, and still refuses an inline part without one. Test: "sends the content ID of a related resource that has no Content-Disposition".
…livery Brings posthog-ruby#325's upload flow up through #328. Attachments now upload to file storage and the send names them by SHA-256, so the Action Mailer specs check the bytes storage received for each file the send names, against a fake upload route and storage. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…etries A multipart/related part with a Content-ID is a resource the HTML refers to, never a body: one without a filename is refused, and one without an inline Content-Disposition keeps its Content-ID. DeliveryError#retryable? now follows the rule PostHog::Emails retries by: a used-up upload quota is permanent, and file storage's 500, 502 and 504 pass like its 503. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
PostHog's send API refuses a template_key over 256 characters since PostHog/posthog#134247. An explicit X-PostHog-Template-Key over 256 is refused before any request, and a derived <mailer>-<action> key is cut to 256. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
SDK performance: posthog-rubyBenchmarks completed. No changes flagged for review. Flags require at least a 5% change in the median and all six pairs agreeing on direction. This is a noise filter, not proof of a performance change or a CI gate. View all results
Values are medians of paired measurements. Not flagged does not mean unchanged. Unavailable means a measurement could not be provided, not zero. Estimated allocation measurements retain their instrumentation uncertainty. RSS measures the whole process, not just SDK allocations; observed peaks are sampled checkpoints. Paired ranges in the diagnostics describe variability, not confidence intervals. Each shard uses its own runner; compare Before PR against With PR within a row, not across shards. Compared 102 metric rows; 102 rows shown in all results. Omitted or shortened data remain in |
…lobal load hook The spec ran the Railtie's initializer, which left its :action_mailer load hook registered for the whole suite. A spec that runs that load hook on a stand-in class then called add_delivery_method on it. The spec now does what the hook does on ActionMailer::Base; 'a Rails app' still boots the Railtie's own hook. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ame every refusal Action Mailer encodes a mail before it delivers it, and encoding gives every inline part a Content-ID, so a Content-ID no longer makes a part a file. Two bodies must share their nearest multipart/alternative, since PostHog sends them as alternatives. The SDK's argument checks raise UnsupportedMailError invalid_mail, and with raise_delivery_errors off the error goes to the log, since Mail drops it. A spec holds DeliveryError#retryable? to the SDK's own retry rule. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Booting an app in development writes tmp/local_secret.txt into the working directory, which nothing ignores, so a run of the suite left a secret in the checkout for the next commit to pick up. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…es outside in Two bodies go out as alternatives only when the nearest container they share is multipart/alternative, so alternative[mixed[text, html]] is refused too. Body kinds are checked first, so an image without a filename is refused by its MIME type. The retry drift spec now sends each failure through a client that retries once, instead of calling the SDK's private rule. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…into fix-329-r1 # Conflicts: # posthog-rails/lib/posthog/rails/railtie.rb # public_api_snapshot.txt # scripts/public_api_snapshot.rb
X-PostHog-Track-Opens, X-PostHog-Track-Clicks and X-PostHog-Capture-Engagement set tracking.opens, tracking.clicks and tracking.engagement, and X-PostHog-Sensitive sets sensitive. Each takes true or false, and none is sent. The adapter never sends capture_engagement, so a send can't carry it next to tracking. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…quest Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Problem
A Rails app that sends mail through Action Mailer can't pick PostHog as its provider. To send through PostHog today it has to replace each mailer call with
PostHog.emails.sendand losedeliver_later, previews and mailer tests.Part of PostHog/michaelr-context#43. Stacks on #328, the
integration:option this PR passes; merge that first.Merge Danger
Warning
🟡 Merge risk: medium · two-way door at merge, one-way once posthog-rails releases this changeset:
delivery_method :posthog, itsX-PostHog-*header vocabulary, its refusal codes and its two error classes become a public contract, and each mail an app sends through it is sentdelivery_method = :posthogchange: each mail goes out as one PostHog email through the SDK, or raisesUnsupportedMailErrorbefore any request when PostHog can't carry part of it. On feat(emails): name the integration that sends an email #328 the same setting raises, so no app sends this way at merge; after the release, only apps that opt in do.mailcall records<mailer>-<action>on the message. Its mail is unchanged, covered by the booted-app spec "leaves an app on another delivery method sending as before", which passes on feat(emails): name the integration that sends an email #328's head and here and fails a mutant that trims recipients in that hook. Apps without Action Mailer load none of it ("boots without Action Mailer").config.action_mailer.delivery_method: setting it back stops every send before the mapper runs. Themailhook has none; it is covered above.Rollout
action-mailersends once PostHog/posthog#130017 labels them.Summary
deliver_nowanddeliver_laterthen send each mail as one PostHog email through the clientPostHog.initmade (it needssecret_key)."Doe, Jane" <jane@example.com>). HTML and text bodies, cc, bcc, reply-to and attachments go through; attachments upload through the SDK, and an inline attachment sends its Content-ID as written.X-PostHog-Distinct-Id,X-PostHog-Template-KeyandX-PostHog-Idempotency-Key.X-PostHog-Track-Opens,X-PostHog-Track-ClicksandX-PostHog-Capture-Engagementsettracking;X-PostHog-Sensitivesetssensitive. Each takestrueorfalse. Click tracking with open tracking off is refused, since PostHog needs the pixel to track clicks.X-PostHog-Sensitive, a mail takes the setting of the PostHog template with its key, and is sensitive when no template has it.X-PostHog-Template-Key, else<mailer>-<action>such asuser_mailer-welcome(made safe:Admin::UserMailer#welcome_emailbecomesadmin-user_mailer-welcome_email, at most 256 characters), elsedefault_template_key, elseaction-mailer.PostHog::Rails::UnsupportedMailErrorwithrefusalset to the code. Nothing is dropped silently.multiple_to), or two From addresses.inline_without_cid), or an attachment without a filename.unsupported_header); a non-normal priority (unsupported_priority).multipart/alternative(unsupported_part). Onlymultipart/mixed,alternativeandrelatedcontainers are opened.envelope_mismatch), a template header (template_unsupported), or an invalid explicit key (invalid_template_key).invalid_mail).PostHog::Rails::DeliveryErrorwithstatus,code,detail,attr,retry_afterandretryable?. The SDK's own retries run first, with one idempotency key.raise_delivery_errors; with it off, the error goes toPostHog::Logging.logger, since Mail drops it.mail.message_idis PostHog's message ID, ready forPostHog.emails.get.X-PostHog-Integration: action-mailer/<posthog-rails version>.Changeset:
posthog-railsminor.actionmailerjoins the development dependencies only; the gem still depends onrailtiesalone.Evidence
posthog.action_mailerinitializer. Each review fix started as a failing test.ed1a910): the lane gate on Ruby 3.3,bundle exec rspec2610 examples, 0 failures (49 pending, the OpenTelemetry-bundle specs);bundle exec rubocopno offenses;bundle exec rake public_api:checkpasses, with the delivery method in the snapshot.Mail::Messages and delivered withmail.deliver. Case 12 (tags) is refused, as Action Mailer has no slot for it; 15 and 17 are for adapters that carry templates.retryable?and the SDK's own retries disagree, across every status and code.Rails::Application#initialize!in a subprocess):deliver_nowwith keyuser_mailer-welcomeandposthog_settings,deliver_latercarrying the mail's idempotency key, an app on another delivery method, and an app without Action Mailer.95a00a9;ed1a910adds only a test): the docs'rescue_fromhandler, run on Rails 7.2 and Rails 6.1 jobs against a fake API. A 400 sends once, a 503 retries to five sends, a refused mail sends nothing; each is logged and reported, and no job is left.9449b6e, before the review rounds, returned202with PostHog's message ID; this head changes the request since then, so it doesn't count.Seams: the
X-PostHog-Integrationvalue is read by the send API's instrumentation (PostHog/posthog#130017, still open, so production ignores it today). The reserved header names, the tracking mapping and the refusal codes are shared with the Nodemailer, Symfony and Laravel adapters.Agent context
Decisions
tracking.opensandtracking.clicks,sensitivepassed through, nevercapture_engagementbeside themcategoryin scope?X-PostHog-*headers, read and never sent<mailer>-<action>, thendefault_template_key, thenaction-mailermailcall records<mailer>-<action>on the message; Mail itself only knows the mailer classretryable?stay in step with the SDK?EmailError#retryable?in the SDKUnsupportedMailErrorinvalid_mail, like every other refusalraise_delivery_errorsoff?unsupported_headerbefore any requestInvolvement: no grilling or prototype rounds; three cross-model review rounds and four final reads (GPT-6.1 Sol), ReviewHog; proof captured, live run owed to the launch train.
Taken over in place from the earlier thread on the same ticket; its commits and authorship are kept.
🤖 Generated with Claude Code