SendDart in Ruby Applications: Make Jobs and Global Configuration Explicit

TL;DR

• Decide that the application must make notification intent, job ownership and global configuration explicit so the app—not ad-hoc controllers—defines durable delivery and recovery behavior across workers and deployments.
• Use stable identifiers and deliberate SDK setup: serialize identity into jobs, avoid live objects, and choose module-level SDK configuration with tenant isolation to keep each job’s credentials correct.
• Limit unintended repeats and verify recovery paths: understand combined retry behavior, preserve a stable send key and test concurrency and failure modes with fictional tenants and simulated interruptions.

Start with the application's job model

Ruby applications can send email from a controller, a background job or a scheduled script. The right integration depends on which process owns the work and how that process recovers from interruption. A successful method call in a console does not establish the behavior of a production worker fleet.

For a Rails application, Active Job provides a common interface to background jobs, while the selected backend determines important execution characteristics. Review the backend and deployment arrangement actually in use. Rails Active Job guide.

Define a notification service that accepts a business purpose and a durable record identifier. Keep the provider SDK behind that service so controllers and models do not each invent their own retry and credential rules.

Related reading: Best Email API: Choose With a Production Acceptance Test.

Related reading: Scheduled Email Delivery: Store the Time, Content and Cancellation State.

Commit the business event before external delivery

A notification should describe a business event that actually committed. Sending from a model callback inside an unfinished transaction can produce a message for data that later rolls back. A callback after commit addresses timing but still needs a durability plan for the handoff to external work.

For critical notifications, retain an outbox or notification record with the business transaction. A job can then process that record, and another dispatcher can discover it if the initial enqueue signal is lost. The exact implementation depends on the database and job backend.

Keep the purpose explicit. An account update, an administrative import and a new signup may all touch the same model but should not necessarily produce the same welcome message. A named application operation is easier to review than a hidden side effect on every save.

Serialize identity, not live objects

A job should receive stable identifiers and load the intended data under the correct scope. Avoid passing a live SDK client, open file or mutable request context. Understand how your job framework serializes model references and what happens if the referenced record changes or disappears before execution.

Decide which content is immutable. A receipt should reference the transaction snapshot, while current suppression and sender permission should be rechecked near sending. If a template changes between attempts, do not silently change the payload under the original operation identity.

Store a template version or rendered content according to your retention policy. Keep private tokens protected and out of generic job arguments visible to every operations user. The worker needs the minimum data required to fulfill the notification.

Configure the Ruby SDK deliberately

SendDart's Ruby SDK uses module-level configuration and returns parsed response data on success. Documented API failures raise SendDart::Error with structured status and name information. Read that interface rather than translating examples from another language. SendDart Ruby SDK.

Load credentials from trusted server configuration. If different tenants use different credentials, do not mutate shared global configuration concurrently without an isolation design. A threaded worker can execute more than one job at a time, so apparent sequential behavior in a console is not sufficient evidence.

Choose a supported configuration and execution boundary that keeps each tenant's credential attached to its job. Test concurrent jobs for two fictional tenants and inspect the transport association without printing the secret values.

Keep retry policies from multiplying

The SDK and the job backend may both retry. Understand their combined behavior before enabling broad retry-on-error rules. A malformed payload should not consume repeated worker attempts, and an uncertain send should not become a new operation merely because the job framework reran perform.

Use a stable key for the supported SendDart send operation and preserve it with the notification record. Keep the same payload during recovery. An original provider ID or partial progress requires reconciliation before creating replacement work.

Separate transient scheduling from final state. A job delayed by a rate restriction may still represent a valid notification; an expired invitation may no longer be useful. Store a deadline or validity rule so the worker can stop stale work deliberately.

Design the webhook outside the controller's usual trust model

A provider callback is not an authenticated browser session. Verify its signature using the required raw request body and signing secret, then validate the event. Plan middleware so parsing does not destroy the bytes the verifier needs.

Persist a unique observation before slow processing. Duplicate callbacks should not create duplicate suppression records, support alerts or conversation messages. Correlate through provider and notification identifiers, using stored ownership to enforce tenant scope.

Keep event processing separate from model callbacks that could trigger another send unintentionally. Updating a delivery status should not recreate the original notification. Tests should exercise that feedback path explicitly.

Review shutdown and deployment behavior

Workers can stop during a deployment. Stop claiming new work gracefully where supported, but assume an external request can still be interrupted. Preserve the job's operation identity and last known stage so a replacement worker can recover safely.

Do not treat a job backend's failed state as proof that no email was accepted. A failure may have occurred after the provider operation. The application notification history needs to retain that distinction independently of the backend's retry counter.

Test a rollback, lost enqueue signal, duplicate job and worker interruption. Add a controlled simulator integration to verify the SDK path and event correlation. These tests should use fictional data and addresses intended for testing.

A maintainable Ruby integration makes configuration, serialization and transaction timing visible. The job framework runs the work, but the application remains responsible for intent, isolation and safe recovery.