Deliveries

Deliveries

A delivery represents a single attempt to send a notification through a specific channel to a user. While a notification contains the information to be communicated, a delivery tracks the actual transmission of that information through a particular communication method.

Understanding Deliveries

When a notification is created by a notiflow, it can be delivered through multiple channels. Each channel delivery is tracked as a separate delivery record. This allows you to monitor the success, failure, or status of each delivery attempt independently.

For example, if a notification is sent via both email and SMS:

• There is one notification (the information being communicated)
• There are two deliveries (one for email, one for SMS)

Delivery Lifecycle

A delivery goes through several states during its lifecycle:

Pending

When a delivery is first created, it starts in a pending state. This means the delivery has been queued but hasn't yet been sent to the channel provider.

Processing

The delivery moves to processing when Notiflows begins the actual transmission process, communicating with the channel provider (email service, SMS gateway, push notification service, etc.).

Sent

A delivery is marked as sent when it has been successfully transmitted to the channel provider. This doesn't guarantee the user has received it, but indicates the provider accepted the delivery request.

Delivered

For channels that support delivery confirmation (like email read receipts or push notification delivery confirmations), the delivery status updates to delivered when the provider confirms the message reached the user's device or inbox.

Failed

If a delivery cannot be completed, it's marked as failed. This can happen for various reasons:

• Invalid recipient information (bad email address, phone number)
• Channel provider errors or outages
• Rate limiting or quota exceeded
• Network issues or timeouts

Bounced

Some channels support bounce detection. If a delivery bounces (email is rejected, phone number is invalid), it's marked accordingly so you can update your user data.

Delivery Tracking

Each delivery includes detailed information:

• Channel: Which communication method was used (email, SMS, push, etc.)
• Status: Current state of the delivery
• Timestamps: When the delivery was created, sent, and (if applicable) delivered
• Provider Response: Any error messages or status codes from the channel provider
• Retry Information: Whether the delivery was retried and how many attempts were made

Retry Logic

Notiflows automatically retries failed deliveries using an exponential backoff strategy. This means:

• Initial retries happen quickly
• Subsequent retries wait longer between attempts
• There's a maximum number of retry attempts
• Some failure types (like invalid recipient information) are not retried

This ensures temporary issues (network problems, provider outages) don't permanently prevent delivery while avoiding unnecessary retries for permanent failures.

Delivery Methods

Different channels have different delivery characteristics:

Email Deliveries

• Can be tracked through open rates and click tracking (if enabled)
• May bounce if the email address is invalid
• Can be marked as spam by email providers
• Delivery confirmation depends on the email provider

SMS Deliveries

• Typically have faster delivery confirmation
• May fail if the phone number is invalid or the carrier blocks the message
• Have character limits that affect message formatting

Push Notification Deliveries

• Require valid device tokens
• May fail if the app is uninstalled or tokens are invalid
• Delivery is usually confirmed quickly by the push service

In-App Deliveries

• Delivered immediately when the user is online
• Stored for later delivery if the user is offline
• Don't require external providers

Monitoring Deliveries

You can monitor deliveries through:

• Delivery Logs: View all deliveries, filter by status, channel, or time period
• Analytics: Track delivery rates, success rates, and failure reasons
• Webhooks: Receive real-time notifications about delivery status changes
• API Queries: Programmatically retrieve delivery information

Best Practices

• Monitor Failure Rates: Regularly check delivery logs to identify patterns in failures
• Update User Data: When deliveries fail due to invalid contact information, update your user records
• Respect Rate Limits: Be aware of channel provider rate limits to avoid delivery failures
• Handle Bounces: Implement logic to handle bounced deliveries and update user preferences accordingly
• Track Metrics: Use delivery data to understand which channels work best for your users

Delivery vs. Notification

Remember the key distinction:

• Notification: The information being communicated (created once per event)
• Delivery: An attempt to send that notification through a specific channel (one per channel per notification)

This separation allows you to:

• Track which channels successfully delivered the information
• Retry failed deliveries without recreating the notification
• Provide users with delivery status information
• Analyze channel performance and reliability

By understanding deliveries, you gain visibility into how your notifications are reaching users and can optimize your notification strategy based on real delivery data.