📥 Inbound Messages

Receive replies to your notifications and process them in your application. NotificationAPI captures inbound email and SMS messages and delivers them to your webhook endpoint.

Overview

When you send notifications to your users, they may want to reply. NotificationAPI provides two powerful features for handling these replies:

1. Inbound Webhooks - Receive email and SMS replies via HTTP webhooks
2. SMS Auto-Reply - Automatically respond to inbound SMS messages

All inbound messages are also visible in your Logs dashboard for debugging and customer support.

Dashboard Setup

For the webhooks, make sure to enable them in the Dashboard > Webhooks section.

Email Inbound Webhook

How It Works

When you send an email notification, NotificationAPI automatically sets the reply-to address to a special NotificationAPI address (e.g., reply-{trackingId}@replies.notificationapi.com).

When a recipient replies to your email:

1. The reply is sent to the NotificationAPI reply address
2. NotificationAPI processes the email and extracts the content
3. NotificationAPI forwards the reply to your configured webhook endpoint
4. The reply appears in your Logs dashboard

Webhook Payload

When an email reply is received, your webhook will receive a POST request with the following JSON payload:

{
  eventType: 'EMAIL_INBOUND',
  from: string,           // Sender's email address
  to: string,             // Original recipient (your reply-to address)
  subject: string,        // Email subject line
  bodyText?: string,      // Plain text body (if available)
  bodyHtml?: string,      // HTML body (if available)
  attachments?: Array<{
    filename: string,
    contentType: string,
    size: number
  }>,
  receivedAt: string,     // ISO 8601 timestamp
  trackingId: string,     // Original notification's tracking ID
  userId: string,         // User ID from the original notification
  type: string            // Notification type from the original notification
}

SMS Inbound Webhook

How It Works

When you send an SMS notification, and the recipient responds within 7 days:

1. NotificationAPI receives the inbound SMS from the carrier
2. NotificationAPI matches the reply to the original conversation
3. NotificationAPI forwards the reply to your configured webhook endpoint
4. The reply appears in your Logs dashboard

Webhook Payload

When an SMS reply is received, your webhook will receive a POST request with the following JSON payload:

{
  eventType: 'SMS_INBOUND',
  from: string,           // Phone number of the end-user
  to: string,             // Your NotificationAPI SMS number
  text: string,           // Message content
  receivedAt: string,     // ISO 8601 timestamp
  userId: string,         // The user's User ID in our system - equal to the userId you passed in the send request
  lastTrackingId: string  // Tracking ID of your last outbound message
}

SMS Auto-Reply

Automatically respond to inbound SMS messages. Useful for scenarios such as:

• “We don’t monitor replies to this number.”
• “We received your message. Our team will respond shortly.”

API Configuration

Configure auto-reply when sending an SMS notification by adding the autoReply option to your send request:

{
  type: 'appointment_reminder',
  to: {
    id: 'user_123',
    number: '+15005550006'
  },
  sms: {
    autoReply: {
      message: 'Thanks for confirming! We look forward to seeing you.'
    }
  }
};

Auto-Reply Parameters

Behavior

• Once per recipient: Auto-reply is sent only once per phone number per account. If the same user sends multiple messages, they will only receive the auto-reply on their first message.
• Opt-out keywords: If the inbound message is an opt-out keyword (STOP, STOPALL, UNSUBSCRIBE, CANCEL, END, or QUIT), the auto-reply is not sent. Instead, the user is unsubscribed from SMS notifications.
• Logged: Auto-replies are logged in your Logs dashboard for visibility.

Costs

Both inbound webhooks and auto-replies count towards your email and SMS usage.

Example:

- Your software sends 1 SMS segment to user A -> 1 SMS usage
- User replies to the SMS -> 1 SMS usage
- Your software sends an auto-reply to user A -> 1 SMS usage

Total usage: 3 SMS usage

Logs

All inbound and auto-reply messages are logged in your Logs dashboard under the original outbound message.

You can:

• Filter by status to Replied or AutoReplied to see inbound and auto-reply messages
• Search by user ID or phone number
• View the full content of inbound and auto-reply messages