@bigbinary/neeto-email-pipeline-frontend 1.0.3 → 1.0.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (42) hide show
  1. package/README.md +476 -44
  2. package/app/javascript/src/translations/ar.json +8 -3
  3. package/app/javascript/src/translations/bg.json +8 -3
  4. package/app/javascript/src/translations/ca.json +8 -3
  5. package/app/javascript/src/translations/cs.json +8 -3
  6. package/app/javascript/src/translations/da.json +8 -3
  7. package/app/javascript/src/translations/de.json +8 -3
  8. package/app/javascript/src/translations/es-MX.json +8 -3
  9. package/app/javascript/src/translations/es.json +8 -3
  10. package/app/javascript/src/translations/et.json +8 -3
  11. package/app/javascript/src/translations/fi.json +8 -3
  12. package/app/javascript/src/translations/fil.json +8 -3
  13. package/app/javascript/src/translations/fr.json +8 -3
  14. package/app/javascript/src/translations/he.json +8 -3
  15. package/app/javascript/src/translations/hi.json +8 -3
  16. package/app/javascript/src/translations/hr.json +8 -3
  17. package/app/javascript/src/translations/hu.json +8 -3
  18. package/app/javascript/src/translations/id.json +8 -3
  19. package/app/javascript/src/translations/it.json +8 -3
  20. package/app/javascript/src/translations/ja.json +8 -3
  21. package/app/javascript/src/translations/ko.json +8 -3
  22. package/app/javascript/src/translations/nl.json +8 -3
  23. package/app/javascript/src/translations/pl.json +8 -3
  24. package/app/javascript/src/translations/pt-BR.json +8 -3
  25. package/app/javascript/src/translations/pt.json +8 -3
  26. package/app/javascript/src/translations/ro.json +8 -3
  27. package/app/javascript/src/translations/ru.json +8 -3
  28. package/app/javascript/src/translations/sk.json +8 -3
  29. package/app/javascript/src/translations/sl.json +8 -3
  30. package/app/javascript/src/translations/sv.json +8 -3
  31. package/app/javascript/src/translations/th.json +8 -3
  32. package/app/javascript/src/translations/tr.json +8 -3
  33. package/app/javascript/src/translations/uk.json +8 -3
  34. package/app/javascript/src/translations/vi.json +8 -3
  35. package/app/javascript/src/translations/zh-CN.json +8 -3
  36. package/app/javascript/src/translations/zh-TW.json +8 -3
  37. package/dist/.ready +1 -1
  38. package/dist/EmailLogs.js +5 -0
  39. package/dist/EmailLogs.js.map +1 -1
  40. package/dist/cjs/EmailLogs.js +5 -0
  41. package/dist/cjs/EmailLogs.js.map +1 -1
  42. package/package.json +18 -18
package/README.md CHANGED
@@ -1,19 +1,130 @@
1
1
  # neeto-email-pipeline-nano
2
2
 
3
- The `neeto-email-pipeline-nano` acts as the source of truth for the new nano's
4
- structure, configs, data etc.
3
+ A Rails engine that consolidates all outbound email infrastructure for neeto
4
+ apps: email prefixing, interception, rate limiting, delivery logging,
5
+ SparkPost webhook handling, and email open tracking.
5
6
 
6
7
  ## Contents
7
8
 
8
- 1. [Development with Host Application](#development-with-host-application)
9
+ 1. [Architecture Overview](#architecture-overview)
10
+ 2. [Development with Host Application](#development-with-host-application)
9
11
  - [Engine](#engine)
10
12
  - [Installation](#installation)
11
- - [Usage](#usage)
12
- - [Frontend package](#frontend-package)
13
+ - [Configuration](#configuration)
14
+ - [Frontend Package](#frontend-package)
13
15
  - [Installation](#installation-1)
14
- - [Instructions for development](#instructions-for-development)
15
- - [Usage](#usage-1)
16
- 2. [Instructions for Publishing](#instructions-for-publishing)
16
+ - [Components](#components)
17
+ 3. [Features](#features)
18
+ - [Email Prefixer](#email-prefixer)
19
+ - [Email Interception](#email-interception)
20
+ - [Rate Limiting](#rate-limiting)
21
+ - [Email Logging](#email-logging)
22
+ - [SparkPost Webhooks](#sparkpost-webhooks)
23
+ - [Email Open Tracking](#email-open-tracking)
24
+ 4. [Testing Locally](#testing-locally)
25
+ 5. [Instructions for Publishing](#instructions-for-publishing)
26
+
27
+ ## Architecture Overview
28
+
29
+ Every outbound email passes through the following pipeline, whether sent via
30
+ `deliver_later` (Sidekiq) or `deliver_now` (inline). The engine detects the
31
+ delivery path automatically and captures organization context from Sidekiq
32
+ middleware or custom mail headers accordingly.
33
+
34
+ ```mermaid
35
+ flowchart TD
36
+ A[Mailer.deliver_later] --> B[Sidekiq Queue]
37
+ B --> C["EmailLogMiddleware
38
+ Generates UUID, sets Thread.current context"]
39
+ C --> D["MailThrottleMiddleware
40
+ Checks hourly rate limit per org"]
41
+
42
+ D -->|Rate limited| E["Reschedule job with backoff
43
+ Preserves email_log_uuid in job hash"]
44
+ E --> R["EmailLogMiddleware handle_post_yield
45
+ Creates rate_limited placeholder
46
+ (email: nil, rate_limited_at set)"]
47
+ R -->|"Job re-enters queue
48
+ with same UUID"| B
49
+
50
+ D -->|Allowed| F[Build Mail Object]
51
+
52
+ DN[Mailer.deliver_now] --> DN1["after_action callback
53
+ Sets X-Neeto-Organization-Id,
54
+ X-Mailer-Class, X-Mailer-Action headers"]
55
+ DN1 --> F
56
+
57
+ F --> T{"EmailOpenTrackable
58
+ included & trackable present?"}
59
+ T -->|Yes| U["after_action injects 1×1 pixel
60
+ EmailOpenReceipt created with HMAC token"]
61
+ U --> G
62
+ T -->|No| G
63
+
64
+ G["EmailPrefixer
65
+ Adds [STAGING]/[DEV] prefix to subject"]
66
+ G --> H["Interceptor
67
+ Drops/forwards based on environment"]
68
+ H -->|Dropped| I["LoggingInterceptor
69
+ Mark as dropped with reason"]
70
+ H -->|Allowed| J["LoggingInterceptor
71
+ Deletes rate_limited placeholder (if any),
72
+ creates per-recipient log records
73
+ with rate_limited_at preserved"]
74
+ J --> K[Mail Delivery]
75
+ K --> L["LoggingObserver
76
+ Mark queued records as handed_over"]
77
+ L --> M{Delivery Method?}
78
+ M -->|SparkPost| N[SparkPost Delivers Email]
79
+ N --> O[SparkPost Webhook]
80
+ O --> P["SparkpostWebhookJob
81
+ Match via email_log_uuid in rcpt_meta"]
82
+ P --> Q2[Update Status: Delivered / Bounced / Spam]
83
+ M -->|Gmail / Outlook / SMTP| S["Final status: handed_over
84
+ No further tracking available"]
85
+
86
+ C -->|Exception| Q[Mark as Failed]
87
+
88
+ subgraph "Asynchronous — triggered when recipient opens email"
89
+ W[Recipient Opens Email] --> X["GET /neeto_email_pipeline/
90
+ email_open_receipts/:token.png"]
91
+ X --> Y["EmailOpenReceiptsController
92
+ Updates first_opened_at, open_count"]
93
+ Y --> Z[Returns 1×1 transparent PNG]
94
+ end
95
+
96
+ style DN fill:#60a5fa,color:#000
97
+ style DN1 fill:#60a5fa,color:#000
98
+ style E fill:#fbbf24,color:#000
99
+ style R fill:#fbbf24,color:#000
100
+ style I fill:#f87171,color:#000
101
+ style Q2 fill:#34d399,color:#000
102
+ style S fill:#94a3b8,color:#000
103
+ style Q fill:#f87171,color:#000
104
+ style U fill:#a78bfa,color:#000
105
+ style Y fill:#a78bfa,color:#000
106
+ style Z fill:#a78bfa,color:#000
107
+ ```
108
+
109
+ > **deliver_now vs deliver_later:** The `deliver_later` path (yellow nodes) goes
110
+ > through Sidekiq middleware for rate limiting and context setup. The
111
+ > `deliver_now` path (blue nodes) skips Sidekiq entirely — organization context
112
+ > is provided via custom mail headers (`X-Neeto-Organization-Id`,
113
+ > `X-Mailer-Class`, `X-Mailer-Action`) set by an `after_action` callback. These
114
+ > headers are stripped before the email leaves the system.
115
+
116
+ ### Email Lifecycle Statuses
117
+
118
+ | Status | Meaning |
119
+ | ---------------- | ------------------------------------------------------------------------------ |
120
+ | `queued` | Email entered the system |
121
+ | `rate_limited` | Temporarily held due to hourly send limit |
122
+ | `dropped` | Blocked before sending (too many recipients, blocked content, bounced address) |
123
+ | `handed_over` | Successfully passed to SparkPost for delivery |
124
+ | `delivered` | SparkPost confirmed delivery to recipient's mail server |
125
+ | `bounced` | Delivery failed (invalid address, full mailbox, policy rejection) |
126
+ | `spam_complaint` | Recipient marked the email as spam |
127
+ | `failed` | System error before handover (SMTP failure, mail construction error) |
17
128
 
18
129
  ## Development with Host Application
19
130
 
@@ -21,87 +132,408 @@ structure, configs, data etc.
21
132
 
22
133
  #### Installation
23
134
 
24
- 1. Add this line to your application's Gemfile:
135
+ 1. Add the gem to your application's Gemfile:
25
136
 
26
137
  ```ruby
27
- source "NEETO_GEM_SERVER_URL" do
28
- # ..existing gems
138
+ source "NEETO_GEM_SERVER_URL" do
139
+ # ..existing gems
29
140
 
30
- gem 'neeto-email-pipeline-engine'
31
- end
141
+ gem 'neeto-email-pipeline-engine'
142
+ end
32
143
  ```
33
144
 
34
- 2. And then execute:
145
+ 2. Install the gem:
35
146
 
36
147
  ```shell
37
148
  bundle install
38
149
  ```
39
150
 
40
- 3. Add this line to your application's `config/routes.rb` file
151
+ 3. Mount the engine in `config/routes.rb`:
41
152
 
42
153
  ```ruby
43
- mount NeetoEmailPipelineEngine::Engine, at: "/neeto_email_pipeline"
154
+ mount NeetoEmailPipelineEngine::Engine, at: "/neeto_email_pipeline"
44
155
  ```
45
156
 
46
- 4. Add required migrations in the `db/migrate` folder. Run the following
47
- commands to copy the migrations from the engine to the host application.
157
+ 4. Copy and run migrations:
48
158
 
49
159
  ```shell
50
160
  bundle exec rails neeto_email_pipeline_engine:install:migrations
51
161
  bundle exec rails db:migrate
52
162
  ```
53
163
 
54
- #### Usage
164
+ #### Configuration
55
165
 
56
- 1. Replace NeetoEmailPipelineNano with your project name
166
+ ##### constants.yml
57
167
 
58
- Create a `script.rb` file in the project root and paste the script from the
59
- following file.
168
+ Add the following to your `config/constants.yml`:
60
169
 
61
- [Replace project name script](./docs/engine/replace-project-name-script.md)
170
+ ```yaml
171
+ defaults: &defaults
172
+ email_pipeline:
173
+ email_logging_enabled: true
174
+ retention_days: 30
62
175
 
63
- 2. Run the file using the following command:
176
+ development:
177
+ <<: *defaults
64
178
 
65
- ```shell
66
- ruby script.rb
67
- ```
179
+ test:
180
+ <<: *defaults
181
+
182
+ staging:
183
+ <<: *defaults
184
+
185
+ production:
186
+ <<: *defaults
187
+ ```
68
188
 
69
- Notes ⚠️
189
+ ##### secrets.yml (via Vault)
70
190
 
71
- - Don't commit this file.
72
- - Project name should be given in PascalCase.
191
+ Add SparkPost webhook credentials to `config/secrets.yml`:
73
192
 
74
- ### Frontend package
193
+ ```yaml
194
+ defaults: &defaults
195
+ email_pipeline:
196
+ sparkpost_webhook_username: <%= ENV['...'] %>
197
+ sparkpost_webhook_password: <%= ENV['...'] %>
198
+ ```
199
+
200
+ ##### Scheduled Jobs
201
+
202
+ Add the purge job to `config/scheduled_jobs.yml`:
203
+
204
+ ```yaml
205
+ purge_old_email_logs:
206
+ cron: "0 3 * * *"
207
+ class: NeetoEmailPipelineEngine::PurgeOldEmailLogsJob
208
+ description: "Purge email logs older than retention period"
209
+ ```
210
+
211
+ ### Frontend Package
75
212
 
76
213
  #### Installation
77
214
 
78
- 1. Add the `neeto-email-pipeline-frontend` package to the `package.json`
215
+ 1. Add the package:
79
216
 
80
217
  ```shell
81
218
  yarn add @bigbinary/neeto-email-pipeline-frontend
82
219
  ```
83
220
 
84
- ### Instructions for development
221
+ 2. Install peer dependencies (neetoui, neeto-molecules, neeto-commons-frontend,
222
+ neeto-filters-frontend, etc.) if not already present.
223
+
224
+ #### Components
225
+
226
+ The package exports the `EmailLogs` component:
227
+
228
+ ```jsx
229
+ import { EmailLogs } from "@bigbinary/neeto-email-pipeline-frontend";
230
+
231
+ <EmailLogs
232
+ canViewEmailLogs={true}
233
+ breadcrumbs={[
234
+ { text: "Admin panel", link: "/admin" },
235
+ { text: "Email Logs" },
236
+ ]}
237
+ helpUrl="https://neetocalhelp.neetokb.com/p/a-8ed45325"
238
+ />;
239
+ ```
240
+
241
+ **Props:**
242
+
243
+ | Prop | Type | Required | Description |
244
+ | ------------------ | --------- | -------- | ---------------------------------------------------------------- |
245
+ | `canViewEmailLogs` | `boolean` | Yes | Permission gate. If `false`, nothing renders. |
246
+ | `breadcrumbs` | `array` | Yes | Breadcrumb trail for the Header component. |
247
+ | `helpUrl` | `string` | No | URL for the help article. Renders a help icon next to the title. |
248
+
249
+ ## Features
250
+
251
+ ### Email Prefixer
252
+
253
+ Adds environment prefix to email subjects in non-production environments (e.g.,
254
+ `[STAGING]`, `[DEVELOPMENT]`). Also supports per-organization custom prefixes
255
+ via the `email_prefix` field on the Organization model.
256
+
257
+ **Requires:** Every mailer must be called with `organization_id` in params:
258
+
259
+ ```ruby
260
+ UserMailer.with(organization_id: org.id).welcome_email.deliver_later
261
+ ```
262
+
263
+ ### Email Interception
264
+
265
+ The `Interceptor` controls which emails are actually sent based on the
266
+ environment:
267
+
268
+ **Staging/Development:**
269
+
270
+ - Forwards emails to configured addresses (`mail_interceptor.forward_emails_to`
271
+ in secrets)
272
+ - Whitelists specific addresses (`mail_interceptor.whitelisted_emails` in
273
+ secrets)
274
+ - Intercepts emails matching `^cpt.*bigbinary\.com$`
275
+
276
+ **Production:**
277
+
278
+ - Filters out emails to `@example.com` and `@example.net`
279
+
280
+ **All environments — emails are dropped when:**
281
+
282
+ - More than 10 unique recipients across To, CC, and BCC
283
+ - Subject or body contains blocked content patterns (`depop`, `dep0p`)
284
+ - All recipients have bounced 2+ times (checked via NeetoTower API)
285
+
286
+ The drop reason is recorded in the email log's `status_detail` field.
287
+
288
+ > **Note:** If the NeetoTower API is unavailable (timeout, connection refused,
289
+ > 5xx error), the engine treats the bounce count as 0 and allows the email to be
290
+ > sent. Errors are reported to Honeybadger for visibility.
291
+
292
+ ### Rate Limiting
293
+
294
+ The `MailThrottleMiddleware` enforces per-organization hourly email send limits:
295
+
296
+ - Configured via `organization.max_hourly_emails`.
297
+ - Can be globally overridden with `GLOBAL_HOURLY_EMAIL_LIMIT_FOR_ALL_ORGS` env
298
+ var
299
+ - Rate limiting is enabled by default in production, controlled by
300
+ `RATE_LIMIT_ENGINE_ENABLED` env var
301
+ - When rate limited, the job is rescheduled with exponential backoff (60s to
302
+ 30min)
303
+ - A notification is sent to the organization (deduplicated per 10-minute window)
304
+
305
+ ### Email Logging
306
+
307
+ When `email_logging_enabled` is `true`, every outbound email is tracked with:
308
+
309
+ - **Per-recipient records**: One row per recipient (to/cc/bcc) with email,
310
+ subject, from, delivery method
311
+ - **Email body capture**: HTML body stored for preview in the admin UI
312
+ - **Full lifecycle tracking**: queued → rate_limited → handed_over →
313
+ delivered/bounced/spam_complaint
314
+ - **Rate limit awareness**: Records carry `rate_limited_at` timestamp when the
315
+ email was throttled
316
+ - **Automatic purge**: `PurgeOldEmailLogsJob` deletes records older than
317
+ `retention_days`
318
+
319
+ > **deliver_now support:** Emails sent via `deliver_now` are also logged. Since
320
+ > these emails bypass Sidekiq middleware, the engine reads organization context
321
+ > from custom mail headers (`X-Neeto-Organization-Id`, `X-Mailer-Class`,
322
+ > `X-Mailer-Action`) that are set by an `after_action` callback in the mailer.
323
+ > The headers are stripped before delivery so they never reach the recipient.
324
+
325
+ ### SparkPost Webhooks
326
+
327
+ The engine provides a webhook endpoint for SparkPost delivery events:
328
+
329
+ **Endpoint:** `POST /neeto_email_pipeline/webhooks/sparkpost/events`
330
+
331
+ **Authentication:** HTTP Basic Auth using credentials from vault.
332
+
333
+ **Handled events:**
334
+
335
+ - `delivery` → status: `delivered`
336
+ - `bounce`, `out_of_band`, `policy_rejection` → status: `bounced`
337
+ - `spam_complaint` → status: `spam_complaint`
338
+
339
+ **Correlation:** The `LoggingInterceptor` injects `email_log_uuid` into the
340
+ `X-MSYS-API` header metadata. SparkPost echoes this back in webhook events via
341
+ `rcpt_meta.email_log_uuid`, which the `SparkpostWebhookJob` uses to find the
342
+ exact recipient record.
343
+
344
+ #### SparkPost Setup
345
+
346
+ 1. Go to SparkPost → Webhooks → Create Webhook
347
+ 2. **Target URL:**
348
+ `https://app.yourproduct.com/neeto_email_pipeline/webhooks/sparkpost/events`
349
+ 3. **Authentication:** HTTP Basic with username/password from your vault config
350
+ 4. **Events to subscribe:**
351
+ - Delivery: `delivery`
352
+ - Bounce: `bounce`, `out_of_band`, `policy_rejection`
353
+ - Spam: `spam_complaint`
354
+
355
+ ### Email Open Tracking
356
+
357
+ Tracks when recipients open emails by injecting a 1×1 transparent tracking
358
+ pixel into outgoing emails. When the recipient's mail client loads the pixel,
359
+ the engine records the open event.
360
+
361
+ #### Setup
362
+
363
+ 1. Include the `EmailOpenTrackable` concern in your mailer:
364
+
365
+ ```ruby
366
+ class CommentMailer < ApplicationMailer
367
+ include NeetoEmailPipelineEngine::EmailOpenTrackable
368
+ end
369
+ ```
370
+
371
+ 2. Pass `trackable` in your mailer params:
372
+
373
+ ```ruby
374
+ CommentMailer.with(
375
+ organization_id: org.id,
376
+ trackable: { id: comment.id, klass: "Comment" }
377
+ ).created_email.deliver_later
378
+ ```
379
+
380
+ 3. Override `email_open_tracking_enabled?` on your Organization model:
381
+
382
+ ```ruby
383
+ def email_open_tracking_enabled?
384
+ setting&.read_receipts_enabled?
385
+ end
386
+ ```
387
+
388
+ The default (defined in the engine's `Helpers` concern) returns `false`.
389
+
390
+ #### How It Works
391
+
392
+ - The `EmailOpenTrackable` concern registers an `after_action` that runs after
393
+ the mailer action builds the message.
394
+ - If `params[:trackable]` is present and `organization.email_open_tracking_enabled?`
395
+ returns `true`, the concern:
396
+ 1. Creates an `EmailOpenReceipt` with an HMAC-SHA256 hashed token
397
+ 2. Determines `attribution_scope` (`single_recipient` or `shared_envelope`
398
+ based on CC/BCC presence)
399
+ 3. Appends a 1×1 transparent PNG `<img>` tag before the closing `</body>` tag
400
+ - When the recipient opens the email, their mail client loads the pixel image,
401
+ hitting `GET /neeto_email_pipeline/email_open_receipts/:token.png`.
402
+ - The controller atomically updates `first_opened_at` (set only on the first
403
+ open), `last_opened_at`, and `open_count`.
404
+ - The endpoint always returns a valid 1×1 transparent PNG regardless of token
405
+ validity — no information is leaked about whether a token exists.
406
+
407
+ #### Querying Open Data
408
+
409
+ Host apps query the engine's model directly:
410
+
411
+ ```ruby
412
+ receipt = NeetoEmailPipelineEngine::EmailOpenReceipt.find_by(
413
+ trackable_type: "Comment", trackable_id: comment.id
414
+ )
415
+ receipt&.first_opened_at # => 2026-06-22 14:30:00 UTC
416
+ receipt&.open_count # => 3
417
+ receipt&.attribution_scope # => "single_recipient"
418
+ ```
419
+
420
+ #### Security
421
+
422
+ - Tokens are 256-bit (`SecureRandom.urlsafe_base64(32)`) and stored as
423
+ HMAC-SHA256 digests — a database leak does not expose valid pixel URLs.
424
+ - The pixel endpoint skips all authentication (CSRF, session, org loading).
425
+ - Responses never reveal token validity (always returns a valid PNG).
426
+ - If tracking is disabled after an email is sent, subsequent pixel hits are
427
+ ignored.
428
+
429
+ #### Known Limitations
430
+
431
+ - Email clients that block remote images (Apple Mail Privacy Protection,
432
+ Outlook defaults) will not trigger the pixel — open counts may undercount.
433
+ - Email proxying (Gmail image proxy, Apple MPP) can trigger false positives.
434
+
435
+ ## Testing Locally
436
+
437
+ ### Email Interception
438
+
439
+ To test email forwarding in development, add the following to
440
+ `config/secrets.yml`:
441
+
442
+ ```yaml
443
+ development:
444
+ mail_interceptor:
445
+ forward_emails_to: "your-email@bigbinary.com"
446
+ whitelisted_emails: ""
447
+ ```
448
+
449
+ Emails will be forwarded to the configured address instead of the original
450
+ recipient.
451
+
452
+ ### Rate Limiting
453
+
454
+ Rate limiting is disabled in development by default. To enable:
455
+
456
+ 1. Set `RATE_LIMIT_ENGINE_ENABLED=true` in your environment
457
+ 2. Set the org's hourly limit:
458
+
459
+ ```ruby
460
+ Organization.first.update!(max_hourly_emails: 5)
461
+ ```
462
+
463
+ 3. Send more emails than the limit to trigger throttling
464
+
465
+ ### Email Logging
466
+
467
+ 1. Enable logging in `config/constants.yml`:
468
+
469
+ ```yaml
470
+ development:
471
+ email_pipeline:
472
+ email_logging_enabled: true
473
+ retention_days: 30
474
+ ```
475
+
476
+ 2. Restart Sidekiq (the engine registers interceptors/observers at boot)
477
+
478
+ 3. Send an email from the app and check the Email Logs page in admin panel
479
+
480
+ ### SparkPost Webhooks (Local)
481
+
482
+ To test webhooks locally, use a tunneling service:
483
+
484
+ 1. Start a tunnel to your local server (e.g., `tunn.dev`, `ngrok`)
485
+ 2. Use the tunnel URL as the webhook target in SparkPost
486
+ 3. Add webhook credentials to `config/secrets.yml`:
487
+
488
+ ```yaml
489
+ development:
490
+ email_pipeline:
491
+ sparkpost_webhook_username: "your-username"
492
+ sparkpost_webhook_password: "your-password"
493
+ ```
494
+
495
+ 4. Use a subdomain that maps to a valid organization (e.g., `spinkart.tunn.dev`)
85
496
 
86
- Check the
87
- [Frontend package development guide](https://neeto-engineering.neetokb.com/p/a-d34cb4b0)
88
- for step-by-step instructions to develop the frontend package.
497
+ ### Email Open Tracking
89
498
 
90
- #### Usage
499
+ 1. Enable tracking for the organization:
91
500
 
92
- 1. Import `WelcomeScreen` component from
93
- "@bigbinary/neeto-email-pipeline-frontend"
501
+ ```ruby
502
+ # In the host app, override email_open_tracking_enabled? to return true
503
+ # e.g., in neeto-desk: toggle Read Receipts in Admin Panel > Tickets
504
+ ```
94
505
 
95
- ```javascript
96
- import React from "react";
506
+ 2. Send an email from a mailer that includes `EmailOpenTrackable` and passes
507
+ `trackable` in params.
97
508
 
98
- import { WelcomeScreen } from "@bigbinary/neeto-email-pipeline-frontend";
509
+ 3. Check the intercepted email in `/mailbox` — the HTML source should contain a
510
+ 1×1 `<img>` tag pointing to
511
+ `/neeto_email_pipeline/email_open_receipts/<token>.png`.
99
512
 
100
- const App = () => <WelcomeScreen />;
513
+ 4. Open the image URL in a browser to simulate an email open. Verify the receipt
514
+ was recorded:
101
515
 
102
- export default App;
516
+ ```ruby
517
+ NeetoEmailPipelineEngine::EmailOpenReceipt.last
518
+ # => #<EmailOpenReceipt open_count: 1, first_opened_at: "...">
103
519
  ```
104
520
 
521
+ ### To send actual emails from your local, add the following lines to your development.rb
522
+
523
+ ```ruby
524
+ config.action_mailer.delivery_method = :smtp
525
+ config.action_mailer.perform_deliveries = true
526
+ config.action_mailer.raise_delivery_errors = true
527
+ ```
528
+
529
+ You will also need to add the following env variables:
530
+
531
+ ```ruby
532
+ SPARKPOST_USERNAME=xxx
533
+ SPARKPOST_PASSWORD=xxx
534
+ SPARKPOST_DOMAIN=xxx # a verified Sparkpost domain. Unverified domains will raise errors.
535
+ ```
536
+
105
537
  ## Instructions for Publishing
106
538
 
107
539
  Consult the
@@ -24,7 +24,7 @@
24
24
  "handedOver": "تم تسليمه",
25
25
  "queued": "معلق",
26
26
  "failed": "فشل",
27
- "spamComplaint": "شكوى من البريد العشوائي"
27
+ "spamComplaint": "تم وضع علامة كرسالة غير مرغوب فيها"
28
28
  },
29
29
  "filters": {
30
30
  "recipient": "المستلم",
@@ -44,8 +44,13 @@
44
44
  "failed": "فشل",
45
45
  "emailBody": "محتوى البريد الإلكتروني",
46
46
  "loadingBody": "جارٍ تحميل محتوى البريد الإلكتروني...",
47
- "noBody": "محتوى البريد الإلكتروني غير متوفر."
48
- }
47
+ "noBody": "محتوى البريد الإلكتروني غير متوفر.",
48
+ "rateLimited": "محدودية المعدل",
49
+ "dropped": "تم إسقاطه",
50
+ "markedAsSpam": "تم وضع علامة كرسالة غير مرغوب فيها"
51
+ },
52
+ "helpDescription": "تتبع كل رسالة إلكترونية صادرة من حسابك. مراقبة حالات التسليم وفهم سبب إسقاط الرسائل الإلكترونية أو تأخيرها أو ارتدادها.",
53
+ "debugDeliverability": "تحليل قابلية التسليم"
49
54
  }
50
55
  }
51
56
  }
@@ -24,7 +24,7 @@
24
24
  "handedOver": "Предаден",
25
25
  "queued": "В опашка",
26
26
  "failed": "Неуспешен",
27
- "spamComplaint": "Жалба за спам"
27
+ "spamComplaint": "Означен като спам"
28
28
  },
29
29
  "filters": {
30
30
  "recipient": "Получател",
@@ -44,8 +44,13 @@
44
44
  "failed": "Неуспешен",
45
45
  "emailBody": "Съдържание на имейла",
46
46
  "loadingBody": "Зареждане на съдържанието на имейла...",
47
- "noBody": "Съдържанието на имейла не е налично."
48
- }
47
+ "noBody": "Съдържанието на имейла не е налично.",
48
+ "rateLimited": "Ограничена честота",
49
+ "dropped": "Отхвърлен",
50
+ "markedAsSpam": "Означен като спам"
51
+ },
52
+ "helpDescription": "Проследявайте всяко изходящо имейл съобщение, изпратено от вашия акаунт. Наблюдавайте състоянията на доставката и разберете защо имейлите са били отхвърлени, върнати или забавени.",
53
+ "debugDeliverability": "Отстраняване на проблеми с доставяемостта"
49
54
  }
50
55
  }
51
56
  }
@@ -24,7 +24,7 @@
24
24
  "handedOver": "Entregat",
25
25
  "queued": "En cua",
26
26
  "failed": "Fallit",
27
- "spamComplaint": "Queixa de spam"
27
+ "spamComplaint": "Marcat com a spam"
28
28
  },
29
29
  "filters": {
30
30
  "recipient": "Destinatari",
@@ -44,8 +44,13 @@
44
44
  "failed": "Fallit",
45
45
  "emailBody": "Cos del correu electrònic",
46
46
  "loadingBody": "Carregant el contingut del correu electrònic...",
47
- "noBody": "El contingut del correu electrònic no està disponible."
48
- }
47
+ "noBody": "El contingut del correu electrònic no està disponible.",
48
+ "rateLimited": "Limitat per taxa",
49
+ "dropped": "Eliminar",
50
+ "markedAsSpam": "Marcat com a spam"
51
+ },
52
+ "helpDescription": "Rastreja cada correu electrònic sortint enviat des del teu compte. Controla els estats de lliurament i entén per què els correus electrònics han estat rebutjats, retornats o endarrerits.",
53
+ "debugDeliverability": "Depurar la lliurabilitat"
49
54
  }
50
55
  }
51
56
  }
@@ -24,7 +24,7 @@
24
24
  "handedOver": "Předáno",
25
25
  "queued": "Ve frontě",
26
26
  "failed": "Nepodařilo se",
27
- "spamComplaint": "Stížnost na spam"
27
+ "spamComplaint": "Označeno jako spam"
28
28
  },
29
29
  "filters": {
30
30
  "recipient": "Příjemce",
@@ -44,8 +44,13 @@
44
44
  "failed": "Nepodařilo se",
45
45
  "emailBody": "Tělo e-mailu",
46
46
  "loadingBody": "Načítám obsah e-mailu...",
47
- "noBody": "Obsah e-mailu není k dispozici."
48
- }
47
+ "noBody": "Obsah e-mailu není k dispozici.",
48
+ "rateLimited": "Omezeno",
49
+ "dropped": "Zamítnuto",
50
+ "markedAsSpam": "Označeno jako spam"
51
+ },
52
+ "helpDescription": "Sledujte každý odchozí e-mail odeslaný z vašeho účtu. Monitorujte statusy doručení a pochopte, proč byly e-maily zamítnuty, vráceny nebo zpožděny.",
53
+ "debugDeliverability": "Debugger doručitelnosti"
49
54
  }
50
55
  }
51
56
  }