Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
42 commits
Select commit Hold shift + click to select a range
156067d
feat(emails): send transactional email and read its status
Silthus Nov 2, 2026
16a2c62
fix(emails): forget the parent's requests in a forked child
Silthus Nov 2, 2026
e33feda
fix(emails): retry a send whose response body was cut off
Silthus Nov 2, 2026
d945d75
feat(emails): send cc, bcc and attachments with emails.send
Silthus Nov 4, 2026
90c1afb
fix(emails): answer the round 3 review
Silthus Nov 4, 2026
1a2acc7
Merge remote-tracking branch 'origin/feat/emails-send' into feat/emai…
Silthus Nov 4, 2026
e94874c
fix(emails): retry a refusal whose body broke off
Silthus Nov 4, 2026
0619e4d
Merge remote-tracking branch 'origin/feat/emails-send' into feat/emai…
Silthus Nov 4, 2026
c843d53
test(emails): prove shutdown waits for a send in its retry backoff
Silthus Nov 4, 2026
2171583
Merge remote-tracking branch 'origin/feat/emails-send' into feat/emai…
Silthus Nov 4, 2026
a3a1aab
fix(emails): refuse non-ASCII content as invalid_attachment, take wra…
Silthus Nov 4, 2026
e29b8a7
fix(emails): take line-broken Base64 only in Base64.encode64's layout
Silthus Nov 4, 2026
df3ff92
refactor(emails): name the attachment rules instead of commenting them
Silthus Nov 4, 2026
66b0217
feat(emails): name the integration that sends an email
Silthus Nov 5, 2026
44c945b
Merge remote-tracking branch 'origin/main' into feat/emails-attachments
Silthus Nov 6, 2026
aa2546b
Merge remote-tracking branch 'origin/main' into feat/emails-attachments
Silthus Nov 9, 2026
294a89a
feat(emails): upload attachments, then send them by hash
Silthus Nov 9, 2026
d94b541
refactor(emails): build the files beside the payload, decode Base64 s…
Silthus Nov 9, 2026
c4d93e8
fix(emails): wait for file storage's Retry-After before retrying an u…
Silthus Nov 9, 2026
3cea49b
fix(emails): count the files before reading them, hash only files tha…
Silthus Nov 9, 2026
03b4d0b
fix(emails): keep storage's Retry-After when its upload answer breaks…
Silthus Nov 9, 2026
e56f70c
fix(emails): count each body's UTF-8 bytes towards the email's size
Silthus Nov 9, 2026
592d442
fix(emails): count each body like a file towards the email's size
Silthus Nov 9, 2026
7db66dd
fix(emails): answer QA panel findings and the upload-route 404 contract
Silthus Nov 9, 2026
484811d
perf(emails): check Base64 line widths without splitting the file
Silthus Nov 9, 2026
8b7d237
fix(emails): send files to storage only over https when PostHog is on…
Silthus Nov 10, 2026
7115f4b
fix(emails): retry storage's 500, 502 and 504, and name its 401 as st…
Silthus Nov 10, 2026
4bc4f3f
fix(emails): count the subject towards the email's size as PostHog does
Silthus Nov 10, 2026
547e466
fix(emails): answer the QA panel on the subject round
Silthus Nov 10, 2026
5f86c37
test(emails): run attachment sends against a fake PostHog and file st…
Silthus Nov 10, 2026
fe145f0
test(emails): check uploads against a fake that enforces the signed s…
Silthus Nov 10, 2026
ab93bd5
test(emails): assert stored files, upload quota and accepted email, n…
Silthus Nov 10, 2026
ef6f0ad
test(emails): meter the bytes storage writes, so a repeated upload shows
Silthus Nov 10, 2026
8e2b20a
test(emails): prove storage's Retry-After by storage staying busy, no…
Silthus Nov 10, 2026
011bdd9
fix(emails): count derived text, and name the file an http upload URL…
Silthus Nov 10, 2026
8e2bc63
fix(emails): leave the size of an email without files to PostHog
Silthus Nov 10, 2026
5659e3e
test(emails): show an upload never follows storage's redirect
Silthus Nov 10, 2026
e942d93
Merge remote-tracking branch 'origin/feat/emails-attachments' into fe…
Silthus Nov 13, 2026
6b123ac
test(emails): refuse an integration version the pattern forbids
Silthus Nov 13, 2026
5529c6c
test(emails): take an integration marker at the edges of the pattern
Silthus Nov 13, 2026
7041da8
Merge remote-tracking branch 'origin/main' into feat/rails-email-deli…
Silthus Nov 13, 2026
6f87535
chore(emails): drop the attachments changeset main already released
Silthus Nov 13, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions .changeset/emails-integration-option.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
---
"posthog-ruby": minor
---

`client.emails.send` takes `integration:`, for a library that sends email on the app's behalf, such as a mailer adapter. Pass its name and version, such as `integration: 'action-mailer/3.14.0'`, and the send carries it as the `X-PostHog-Integration` header, so PostHog can tell which integration sent the email. A value outside `name/version` raises `ArgumentError` before any request. The User-Agent doesn't change.
19 changes: 16 additions & 3 deletions lib/posthog/emails.rb
Original file line number Diff line number Diff line change
Expand Up @@ -88,6 +88,7 @@ class Emails
IDEMPOTENCY_KEY_PATTERN = /\A[\x21-\x7e]{1,255}\z/
TEMPLATE_KEY_PATTERN = /\A[a-zA-Z0-9_-]{1,400}\z/
HEADER_TOKEN_PATTERN = /\A[\x21-\x7e]+\z/
INTEGRATION_PATTERN = %r{\A[a-z0-9-]{1,40}/[0-9A-Za-z.+-]{1,40}\z}
JSON_CONTENT = { 'Content-Type' => 'application/json' }.freeze
SEND_KEY_NEEDED = 'Sending email needs secret_key, a project secret API key with the ' \
'transactional_email:write scope.'
Expand All @@ -104,8 +105,9 @@ class Emails
].freeze
private_constant :SEND_PATH, :UPLOADS_PATH, :STATUS_PATH, :US_APP_HOST, :EU_APP_HOST, :CLOUD_APP_HOSTS,
:MAX_RETRY_DELAY_SECONDS, :UUID_PATTERN, :IDEMPOTENCY_KEY_PATTERN, :TEMPLATE_KEY_PATTERN,
:HEADER_TOKEN_PATTERN, :JSON_CONTENT, :SEND_KEY_NEEDED, :READ_KEY_NEEDED, :TEMPLATE_FORM_WHY,
:CODE_FORM_WHY, :TEMPLATE_FIELDS, :CODE_FIELDS, :NETWORK_ERRORS
:HEADER_TOKEN_PATTERN, :INTEGRATION_PATTERN, :JSON_CONTENT, :SEND_KEY_NEEDED,
:READ_KEY_NEEDED, :TEMPLATE_FORM_WHY, :CODE_FORM_WHY, :TEMPLATE_FIELDS, :CODE_FIELDS,
:NETWORK_ERRORS

# @api private
def initialize(secret_key:, host:, app_host:, timeout:, max_retries:, migrated_from:, user_agent:, disabled:,
Expand Down Expand Up @@ -181,6 +183,9 @@ def initialize(secret_key:, host:, app_host:, timeout:, max_retries:, migrated_f
# retries the send.
# @param max_retries [Integer] Overrides the client's `email_request_max_retries` for this send. +0+ turns
# retries off.
# @param integration [String] For a library that sends on the app's behalf, such as a mailer adapter: its name
# and version, such as `action-mailer/3.14.0`, sent as the `X-PostHog-Integration` header. The name is lowercase
# letters, digits and hyphens; the version is letters, digits, dots, plus signs and hyphens; each at most 40.
# @return [SendResult] The queued email.
# @raise [EmailError] PostHog did not queue the email, or the client could not tell whether it did.
# Before any request, {EmailError#code} is `invalid_attachment` for a file the client can't send,
Expand All @@ -193,20 +198,22 @@ def initialize(secret_key:, host:, app_host:, timeout:, max_retries:, migrated_f
def send(
to:, template_id: nil, template_data: nil, template_key: nil, subject: nil, html: nil, text: nil, from: nil,
reply_to: nil, cc: nil, bcc: nil, attachments: nil, sensitive: nil, tracking: nil, capture_engagement: nil,
distinct_id: nil, idempotency_key: nil, max_retries: nil
distinct_id: nil, idempotency_key: nil, max_retries: nil, integration: nil
)
fields = {
template_data: template_data, subject: subject, html: html, text: text, from: from, reply_to: reply_to,
cc: cc, bcc: bcc, attachments: attachments, sensitive: sensitive, tracking: tracking,
capture_engagement: capture_engagement
}.compact
check_recipient(to, distinct_id, idempotency_key, max_retries)
check_integration(integration)
payload = content(template_id, template_key, fields).merge(to: to)
files = EmailAttachments.from(fields.fetch(:attachments, []), bodies_with_derived_text(fields), fields[:subject])
payload[:attachments] = files.references unless files.empty?
payload[:distinct_id] = distinct_id unless distinct_id.nil?
body = JSON.generate(payload)
headers = { 'Content-Type' => 'application/json', 'Idempotency-Key' => idempotency_key || SecureRandom.uuid }
headers['X-PostHog-Integration'] = integration if integration

result = call('no email was sent', SEND_KEY_NEEDED) do |secret_key|
upload(files, secret_key, max_retries || @max_retries) unless files.empty?
Expand Down Expand Up @@ -313,6 +320,12 @@ def check_recipient(to, distinct_id, idempotency_key, max_retries)
raise ArgumentError, 'max_retries must be a nonnegative integer.'
end

def check_integration(integration)
return if integration.nil? || (integration.is_a?(String) && INTEGRATION_PATTERN.match?(integration))

raise ArgumentError, "integration must be a name and version, such as 'action-mailer/3.14.0'."
end

def nonempty_string?(value)
value.is_a?(String) && !value.strip.empty?
end
Expand Down
2 changes: 1 addition & 1 deletion public_api_snapshot.txt
Original file line number Diff line number Diff line change
Expand Up @@ -74,7 +74,7 @@ instance_method PostHog::EmailError#status_code()
instance_method PostHog::EmailError#why()
class PostHog::Emails
instance_method PostHog::Emails#get(message_id)
instance_method PostHog::Emails#send(to:, template_id: ..., template_data: ..., template_key: ..., subject: ..., html: ..., text: ..., from: ..., reply_to: ..., cc: ..., bcc: ..., attachments: ..., sensitive: ..., tracking: ..., capture_engagement: ..., distinct_id: ..., idempotency_key: ..., max_retries: ...)
instance_method PostHog::Emails#send(to:, template_id: ..., template_data: ..., template_key: ..., subject: ..., html: ..., text: ..., from: ..., reply_to: ..., cc: ..., bcc: ..., attachments: ..., sensitive: ..., tracking: ..., capture_engagement: ..., distinct_id: ..., idempotency_key: ..., max_retries: ..., integration: ...)
class_method PostHog::Emails.logger()
class PostHog::Emails::SendResult < Struct
instance_method PostHog::Emails::SendResult#id()
Expand Down
40 changes: 40 additions & 0 deletions spec/posthog/emails_spec.rb
Original file line number Diff line number Diff line change
Expand Up @@ -798,6 +798,46 @@ def refused_attachment(**overrides)
end
end

describe 'integration marker' do
before { stub_request(:post, send_url).to_return(refuse(503, 'delivery_unavailable'), accept) }

it 'names the integration that made the send on every attempt, and keeps the User-Agent' do
send_code(integration: 'action-mailer/3.14.0')

expect(a_request(:post, send_url).with(
headers: { 'X-PostHog-Integration' => 'action-mailer/3.14.0',
'User-Agent' => "posthog-ruby/#{PostHog::VERSION}" }
)).to have_been_made.twice
end

it 'takes a marker at the edges of the name/version every SDK accepts' do
integration = "#{'a1-' * 13}a/#{'3.21.0-rc.1+Build.7'.ljust(40, 'x')}"

send_code(integration: integration)

expect(a_request(:post, send_url).with(headers: { 'X-PostHog-Integration' => integration }))
.to have_been_made.twice
end

it 'sends no marker without the option' do
send_template

expect(a_request(:post, send_url).with { |request| request.headers.key?('X-Posthog-Integration') })
.not_to have_been_made
end

it 'refuses a marker outside name/version before any request' do
[
'action-mailer', 'Action-Mailer/1.0', 'action mailer/1.0', "#{'a' * 41}/1.0", 7,
'action-mailer/', 'action-mailer/1.0 beta', 'action-mailer/1.0/x', 'action-mailer/1_0',
"action-mailer/#{'1' * 41}"
].each do |integration|
expect { send_code(integration: integration) }.to raise_error(ArgumentError, /integration must be/)
end
expect(a_request(:any, %r{/messaging/})).not_to have_been_made
end
end

describe 'client setup' do
it 'maps an EU ingestion host to the EU app host' do
options[:host] = 'https://eu.i.posthog.com/'
Expand Down
Loading