📥 Inbound Messages

Pingram can capture inbound emails and SMS, and deliver them to your webhook endpoint, with automatic reply detection and tracking.

Overview

Pingram provides a complete inbound messaging solution:

1. Unlimited Inboxes - Built-in inbox (e.g., yourcompany@mail.pingram.io) with the ability to add unlimited custom addresses and domains
2. SMS Number - Dedicated A2P-enabled number to send & receive SMS
3. Webhooks - Process incoming messages via webhooks
4. Reply Detection - Automatically detect if a message is a reply and link it to the original thread
5. Auto-Reply - Automatically respond to inbound messages with pre-defined canned messages
6. Inbox Preview - APIs and Dashboard tools to view inbound messages

Email Inbox

Your account comes with a default inbox address in this format: yourcompany@mail.pingram.io

You can customize the prefix from the Dashboard, or add unlimited addresses under your own domain.

Email Inbound Webhook

Webhook Payload

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

{
  eventType: 'EMAIL_INBOUND',
  from: string,             // Sender's email address
  to: string,               // Your Pingram address that received the email
  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
  isReply: boolean,         // true if this is a reply to a previous notification
  type?: string,            // Notification type from the original notification
  references?: string,      // References header for threading
  messageId?: string,       // Original Message-ID header
  inReplyTo?: string,       // In-Reply-To header for threading
  trackingId?: string,      // Original notification's tracking ID
  userId?: string,          // User ID from the original notification
}

Reply Detection

Pingram automatically detects replies in two ways:

1. Reply-to tracking: When you send notifications, we set a unique reply-to address that lets us link replies to the original message
2. Thread matching: We analyze email headers and content to identify replies even when users don’t use the reply-to address

SMS Inbound Webhook

Webhook Payload

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

{
  eventType: 'SMS_INBOUND',
  from: string,             // Phone number of the sender
  to: string,               // Your Pingram SMS number
  text: string,             // Message content
  receivedAt: string,       // ISO 8601 timestamp

  // Reply tracking (only present if this is a reply to a previous message)
  isReply: boolean,         // true if linked to a previous outbound message
  userId?: string,          // The user's ID in your system (if isReply)
  lastTrackingId?: string   // Tracking ID of your last outbound message to this user (if isReply)
}

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: {
    message: 'Your appointment is tomorrow at 2pm. Reply YES to confirm.',
    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

Inbound messages 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.

API Access

In addition to the webhooks, you can programmatically access your inbound messages via the logs list API.