Repository navigation
Conversation
Adds client.emails.send for a template made in PostHog (template_id) or content your code rendered (template_key, subject, html, text), and client.emails.get for the status of a sent email. Ports posthog-node and posthog-python's emails to Ruby: the same wire body, app host rules, idempotency key, retries and error names. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
A child forked while another thread sent email inherited a positive in-flight count that no thread could settle, so shutdown waited for its whole timeout, or forever without one. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Net::HTTP treats a connection closed partway through a body as the end of the body, so a truncated 202 raised a non-retryable api_error. Turn EOF suppression off so the cut-off read raises a network error and the send retries with the same idempotency key. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The code form takes cc and bcc (one address or a list) and attachments: Hashes with filename, content, and an optional content_type and content_id. A binary String, such as File.binread returns, or a list of byte values is encoded as Base64 once, before the retry loop; any other String is taken as Base64 already and must look like it. Empty lists are left out, so a PostHog version without the fields still sends. A file the client can't send raises EmailError invalid_attachment with the field, before any request. Mirrors posthog-node (posthog-js#5514) and posthog-python#1172; the server holds the limits. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
- Explicit nil email options fall back to the defaults, and the client checks them before the worker, instance count and flags poller start. - app_host must be an http or https URL with a host. - A refusal whose body broke off keeps its status and Retry-After; a corrupt compressed body is a network error and retries. - skip_ssl_verification also applies to email requests. - Specs: real-socket server reads whole requests and runs without WebMock, the backoff spec waits on a queue instead of a fixed sleep, and the warning spec reads the logger output. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
A reply whose body broke off is a network error again, so a cut-off 409 idempotency_key_in_flight retries as before. It now keeps the head's Retry-After: the retry waits for it, and one over 30 seconds raises at once. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The spec released the retry on a 50 ms timer, so it passed even when shutdown returned at once. It now holds the retry until it has seen shutdown still running, then releases it and expects true. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…pped Base64 - A String that isn't ASCII, such as a PDF read with File.read or UTF-16 text, raised a bare ArgumentError from the Base64 match. It now raises invalid_attachment with the field and the File.binread hint. - Base64 with line breaks, as Base64.encode64 writes it, is sent without them instead of being refused. - The retry spec checks both attempts carry the encoded file, and the Base64Check helper is inlined. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Removing every line break let a text file read with File.read, such as "ABCD1234\nEFGH5678\n", pass as Base64, so the recipient got a garbled file. Line breaks are now removed only when the content is exactly what Base64.encode64 writes; other text is refused as invalid_attachment. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
A mailer adapter that sends through `client.emails.send` passes `integration: '<name>/<version>'`, and the send carries it as the `X-PostHog-Integration` header, so PostHog can tell which integration sent the email. The User-Agent stays the SDK's. A value outside `name/version` raises ArgumentError before any request. Ticket: PostHog/michaelr-context#43 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
posthog-ruby-sync Compliance ReportDate: 2026-11-13T07:09:55.656579+00:00
|
| Test | Status | Duration |
|---|---|---|
| Format Validation.Event Has Required Fields | ✅ | 9ms |
| Format Validation.Event Has Uuid | ✅ | 5ms |
| Format Validation.Event Has Lib Properties | ✅ | 6ms |
| Format Validation.Distinct Id Is String | ✅ | 7ms |
| Format Validation.Token Is Present | ✅ | 7ms |
| Format Validation.Custom Properties Preserved | ✅ | 5ms |
| Format Validation.Event Has Timestamp | ✅ | 7ms |
| Format Validation.Non Utc Event Timestamp Is Converted To Utc | ✅ | 5ms |
| Retry Behavior.Retries On 503 | ✅ | 5337ms |
| Retry Behavior.Does Not Retry On 400 | ❌ | 7ms |
| Retry Behavior.Does Not Retry On 401 | ❌ | 5ms |
| Retry Behavior.Respects Retry After Header | ✅ | 8016ms |
| Retry Behavior.Implements Backoff | ❌ | 227ms |
| Retry Behavior.Retries On 500 | ✅ | 5147ms |
| Retry Behavior.Retries On 502 | ✅ | 5149ms |
| Retry Behavior.Retries On 504 | ✅ | 5165ms |
| Retry Behavior.Max Retries Respected | ❌ | 548ms |
| Deduplication.Generates Unique Uuids | ✅ | 16ms |
| Deduplication.Preserves Uuid On Retry | ✅ | 5156ms |
| Deduplication.Preserves Uuid And Timestamp On Retry | ✅ | 10340ms |
| Deduplication.Preserves Uuid And Timestamp On Batch Retry | ✅ | 5119ms |
| Deduplication.No Duplicate Events In Batch | ✅ | 18ms |
| Deduplication.Different Events Have Different Uuids | ✅ | 8ms |
| Compression.Sends Gzip When Enabled | ✅ | 6ms |
| Batch Format.Uses Proper Batch Structure | ✅ | 5ms |
| Batch Format.Flush With No Events Sends Nothing | ✅ | 2ms |
| Batch Format.Multiple Events Batched Together | ❌ | 15ms |
| Error Handling.Does Not Retry On 403 | ❌ | 4ms |
| Error Handling.Does Not Retry On 413 | ❌ | 4ms |
| Error Handling.Retries On 408 | ✅ | 5145ms |
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 | ✅ | 10ms |
| 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 | ✅ | 7ms |
| Request Payload.Token In Flags Body Matches Init | ✅ | 7ms |
| Request Payload.Groups Round Trip | ✅ | 5ms |
| Request Payload.Groups Default To Empty Object | ✅ | 5ms |
| Request Payload.Disable Geoip False Propagates As Geoip Disable False | ✅ | 6ms |
| Request Payload.Disable Geoip Omitted Defaults To False | ❌ | 5ms |
| Request Payload.Flag Keys To Evaluate Contains Only Requested Key | ✅ | 5ms |
| Request Lifecycle.No Flags Request On Init Alone | ✅ | 2ms |
| Request Lifecycle.No Flags Request On Normal Capture | ✅ | 5ms |
| Request Lifecycle.Two Flag Calls Produce Two Remote Requests | ✅ | 8ms |
| Request Lifecycle.Mock Response Value Is Returned To Caller | ✅ | 5ms |
| Retry Behavior.Retries Flags On 502 | ✅ | 107ms |
| Retry Behavior.Retries Flags On 504 | ✅ | 109ms |
| Side Effect Events.Get Feature Flag Captures Feature Flag Called Event | ✅ | 8ms |
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:10:49.496478+00:00
|
| Test | Status | Duration |
|---|---|---|
| Format Validation.Event Has Required Fields | ✅ | 109ms |
| Format Validation.Event Has Uuid | ✅ | 107ms |
| Format Validation.Event Has Lib Properties | ✅ | 108ms |
| Format Validation.Distinct Id Is String | ✅ | 106ms |
| Format Validation.Token Is Present | ✅ | 106ms |
| Format Validation.Custom Properties Preserved | ✅ | 106ms |
| Format Validation.Event Has Timestamp | ✅ | 105ms |
| Format Validation.Non Utc Event Timestamp Is Converted To Utc | ✅ | 8ms |
| Retry Behavior.Retries On 503 | ✅ | 5311ms |
| Retry Behavior.Does Not Retry On 400 | ✅ | 2110ms |
| Retry Behavior.Does Not Retry On 401 | ✅ | 2109ms |
| Retry Behavior.Respects Retry After Header | ✅ | 8116ms |
| Retry Behavior.Implements Backoff | ✅ | 15722ms |
| Retry Behavior.Retries On 500 | ✅ | 5213ms |
| Retry Behavior.Retries On 502 | ✅ | 5212ms |
| Retry Behavior.Retries On 504 | ✅ | 5212ms |
| Retry Behavior.Max Retries Respected | ✅ | 15710ms |
| Deduplication.Generates Unique Uuids | ✅ | 113ms |
| Deduplication.Preserves Uuid On Retry | ✅ | 5212ms |
| Deduplication.Preserves Uuid And Timestamp On Retry | ✅ | 10317ms |
| Deduplication.Preserves Uuid And Timestamp On Batch Retry | ✅ | 5214ms |
| Deduplication.No Duplicate Events In Batch | ✅ | 113ms |
| Deduplication.Different Events Have Different Uuids | ✅ | 110ms |
| Compression.Sends Gzip When Enabled | ✅ | 106ms |
| Batch Format.Uses Proper Batch Structure | ✅ | 106ms |
| Batch Format.Flush With No Events Sends Nothing | ✅ | 5ms |
| 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 | ✅ | 5212ms |
Feature_Flags Tests
View Details
| Test | Status | Duration |
|---|---|---|
| Request Payload.Request With Person Properties Device Id | ✅ | 108ms |
| Request Payload.Flags Request Uses V2 Query Param | ✅ | 106ms |
| Request Payload.Flags Request Hits Flags Path Not Decide | ✅ | 108ms |
| Request Payload.Flags Request Omits Authorization Header | ✅ | 107ms |
| Request Payload.Token In Flags Body Matches Init | ✅ | 107ms |
| Request Payload.Groups Round Trip | ✅ | 109ms |
| Request Payload.Groups Default To Empty Object | ✅ | 107ms |
| Request Payload.Disable Geoip False Propagates As Geoip Disable False | ✅ | 107ms |
| Request Payload.Disable Geoip Omitted Defaults To False | ❌ | 107ms |
| Request Payload.Flag Keys To Evaluate Contains Only Requested Key | ✅ | 107ms |
| Request Lifecycle.No Flags Request On Init Alone | ✅ | 3ms |
| Request Lifecycle.No Flags Request On Normal Capture | ✅ | 105ms |
| Request Lifecycle.Two Flag Calls Produce Two Remote Requests | ✅ | 111ms |
| Request Lifecycle.Mock Response Value Is Returned To Caller | ✅ | 107ms |
| Retry Behavior.Retries Flags On 502 | ✅ | 210ms |
| Retry Behavior.Retries Flags On 504 | ✅ | 209ms |
| Side Effect Events.Get Feature Flag Captures Feature Flag Called Event | ✅ | 109ms |
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']
# Conflicts: # lib/posthog/client.rb # lib/posthog/email_error.rb # lib/posthog/emails.rb # public_api_snapshot.txt # spec/posthog/emails_spec.rb
An email now carries up to 10 files and 40 MB after Base64 encoding, about 29 MB of files. The client hashes each file, checks both limits before any request, asks PostHog where to upload the files it doesn't have yet, PUTs them to file storage without the secret key, and sends the files' SHA-256 hashes. A refused upload sends no email and names what storage answered. Refs PostHog/michaelr-context#83 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…trictly Refs PostHog/michaelr-context#83 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…pload Refs PostHog/michaelr-context#83 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…t fit Refs PostHog/michaelr-context#83 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
… off A PUT whose answer broke off raised a network error naming the file but dropped the Retry-After storage had sent, so callers couldn't wait it out. Refs PostHog/michaelr-context#83 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The send carries the bodies as JSON in UTF-8, so a UTF-16 body counted twice its sent size and refused emails the server takes. Refs PostHog/michaelr-context#83 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
PostHog's check counts each body's UTF-8 bytes at their Base64 size with line breaks, as it does a file's. Counting raw bytes let a send pass here and be refused after its uploads. Refs PostHog/michaelr-context#83 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
- A 404 from the upload route raises not_found on attachments with PostHog's own reason, and sends nothing (spec #71, Compatibility). - Base64 content wrapped at 60, 64 or 76 characters, with LF or CRLF, decodes; text in any other line layout is still refused. - A refused upload is named by storage's failure (service_unavailable for 5xx, else application_error), not by PostHog's categories. - Inline cc/bcc assignment; drop inline comments for names. Refs PostHog/michaelr-context#83 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The layout check re-encoded the file and split it into lines for each width, which allocated millions of strings for the largest file. It now walks the line breaks once. Refs PostHog/michaelr-context#83 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
… https An upload URL without https from a PostHog reached over https now stops the send before any file goes out, with a reason and a fix. Local setups that reach PostHog over http still upload over http. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…orage's A PUT to the same signed URL with the same bytes is safe to repeat, so a transient storage error no longer stops the send while retries remain. A storage 401 is no longer reported as a missing PostHog key. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
PostHog's estimate now adds 75 bytes for every 42 bytes of the subject's UTF-8, rounded up, and nothing for an empty subject. The local check matches it, so a long subject beside a near-limit file is refused before any upload. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
- Base64 with lone carriage returns is refused like any other unknown line layout, instead of having them stripped. - Wrapped Base64 reads the same whatever the app's input record separator. - A 404 from the upload route without PostHog's JSON, such as a proxy's page, is still not_found on attachments. - Tests assert what a caller sees: the largest wrapped file is sent with its decoded size, and storage retries are counted at the storage boundary. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…orage The success paths ran against canned answers that accepted any upload and any send. They now run against an in-memory stand-in that behaves like the real routes and bucket: PostHog asks only for the files storage lacks, storage keeps a PUT only when its bytes match the signed SHA-256 and it carries no Authorization, and a send is accepted only when every file it names is stored. The tests assert the bytes in the bucket. Stubs remain only to inject faults. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ize and digest The fake PostHog now refuses a malformed manifest and an unsigned send, and the fake storage takes a PUT only when its bytes match the signed size, checksum and digest. Tests read the stored files and the accepted emails instead of counting requests. Refs PostHog/michaelr-context#83 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ot requests The fake PostHog counts the bytes of each upload slot it issues against the team's daily quota, as the upload route does, so a file uploaded twice shows in the quota. The tests no longer read any request log. Refs PostHog/michaelr-context#83 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The fake storage adds each written file's bytes to a meter, as object storage reports bytes uploaded, so a file sent to storage twice fails the tests. The retry test now rests on the send succeeding and the stored file. Refs PostHog/michaelr-context#83 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…t by sleep's argument The attachment tests run on a fake clock that the client's waits advance. Fake storage answers 503 SlowDown with its Retry-After until that time has passed, so a client that retries early fails the send. Refs PostHog/michaelr-context#83 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
… would carry When text is empty, PostHog derives it from the HTML and counts it, so the local estimate counts the HTML twice; the derived text is never longer. An upload URL without https now refuses on the file's field and names the file, never the URL, unless app_host is an http URL for local development. Refs PostHog/michaelr-context#83 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The local 40 MB estimate guards uploads, so it now runs only when the email has files, as in the Go SDK. Large HTML without files goes to PostHog as before. Refs PostHog/michaelr-context#83 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Fake storage answers the PUT with a 307 to a second, plain-http storage. The second storage receives nothing, the attachment fails with attachment_upload_failed naming the file but not where storage pointed, and no email is sent. Net::HTTP doesn't follow redirects, so only the test is new. Refs PostHog/michaelr-context#83 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…at/rails-email-delivery # Conflicts: # lib/posthog/emails.rb
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 |
…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>
The refused values only covered the name part of name/version. An empty version, a second slash, an underscore and a 41-character version are now refused too, so loosening the version half of the pattern fails a test. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…very # Conflicts: # lib/posthog/emails.rb # public_api_snapshot.txt # spec/posthog/emails_spec.rb
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Problem
A library that sends email for an app through
client.emails.send, such as the Action Mailer delivery method coming next in this stack, has no way to say so. Every send looks like a directposthog-rubycall, so PostHog can't tell which integrations people send through.Part of PostHog/michaelr-context#43. Base is
main. #329 stacks on this branch.Merge Danger
Note
🔵 Merge risk: low · two-way door at merge, one-way once posthog-ruby releases this changeset: the
integration:keyword ofemails.sendand theX-PostHog-Integration: <name>/<version>header become a public contract other integrations build onintegration:change: their sends carry theX-PostHog-Integrationheader on every attempt, and an invalid value raisesArgumentErrorbefore any request. At merge no caller in this repo passes it; feat(rails): send Action Mailer mail through PostHog #329 is the first. Onmainthe same keyword already raisedArgumentError(unknown keyword), so no working send changes.integration:is unchanged, covered by the RSpec WebMock example "sends no marker without the option", which passes onmainand here, and by the unchangedemails.sendsuite.Rollout
Summary
client.emails.sendtakesintegration:, aname/versionstring such asaction-mailer/1.2.3.X-PostHog-Integrationheader, on every retry of that send.posthog-ruby/<version>, and the analytics client is untouched..,+and-; each 1 to 40 characters. Anything else raisesArgumentErrorbefore any request, like every other invalid option.Changeset:
posthog-rubyminor.Evidence
main(4aa70bd): 3 of the 4 integration examples fail withArgumentError: unknown keyword: :integration; the fourth, no header without the option, passes there too.6f87535): the lane gate on Ruby 3.3,bundle exec rspec2545 examples, 0 failures (49 pending, the OpenTelemetry-bundle specs);bundle exec rubocopno offenses;bundle exec rake public_api:checkpasses with the updated snapshot. CI is green.emails.sendmakes, stubbed with WebMock: the header with the option (on both attempts of a retried send), no header without it, values at the edges of the pattern, and no request for an invalid name or version.Seams: the
X-PostHog-Integrationheader is read by the send API's instrumentation (PostHog/posthog#130017, still open); posthog-node and posthog-php gain the same option with the same pattern in their own stacks.SDK spec:
sdk-specs' emails spec lists the send headers and doesn't name this option yet; this adds one optional header and changes none it lists.Agent context
Decisions
X-PostHog-Integration: <name>/<version>header, set by a per-sendintegrationoption; User-Agent unchangedmain?mainalready released attachments, and keeping it would release them againInvolvement: no grilling or prototype rounds; two cross-model review rounds and two final reads (GPT-6.1 Sol), the posthog bot's review; 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