diff --git a/.changeset/emails-integration-option.md b/.changeset/emails-integration-option.md new file mode 100644 index 00000000..ef342989 --- /dev/null +++ b/.changeset/emails-integration-option.md @@ -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. diff --git a/lib/posthog/emails.rb b/lib/posthog/emails.rb index de77249c..8914d884 100644 --- a/lib/posthog/emails.rb +++ b/lib/posthog/emails.rb @@ -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.' @@ -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:, @@ -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, @@ -193,7 +198,7 @@ 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, @@ -201,12 +206,14 @@ def send( 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? @@ -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 diff --git a/public_api_snapshot.txt b/public_api_snapshot.txt index ef26a486..0640f6f1 100644 --- a/public_api_snapshot.txt +++ b/public_api_snapshot.txt @@ -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() diff --git a/spec/posthog/emails_spec.rb b/spec/posthog/emails_spec.rb index 5fd3bfda..e02422e5 100644 --- a/spec/posthog/emails_spec.rb +++ b/spec/posthog/emails_spec.rb @@ -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/'