Recipients Reference

The Recipients field is used to specify message targets. This comprehensive guide covers all available recipient identification methods and advanced features.

Basic Structure

Each recipient is defined as an object within the Recipients array:

{
  "Recipients": [
    {
      "IdaasId": "PL-123654",
      "SendTo": 1
    },
    {
      "IdaasId": "PL-64364",
      "SendTo": 1
    }
  ]
}

Recipient Identification Methods

The system uses a priority-based approach to identify recipients. When multiple identification fields are provided, the system uses the first available method in this order:

1. IDaaS ID

{
  "IdaasId": "PL-12345"
}

• Type: String
• Description: Xporter Identity unique identifier
• Usage: When using Xporter Data

2. Email Address

{
  "EmailAddress": "[email protected]"
}

• Type: String (Email format)
• Description: Email address for contact lookup and message delivery
• Usage: For email messages or contact lookup by email

3. Mobile Number

{
  "MobileNumber": "07700900123"
}

• Type: String (International format)
• Description: Mobile phone number for contact lookup and SMS delivery
• Usage: For SMS messages or contact lookup by phone number

4. Anonymous Contact

In scenarios where an email address or mobile number has been provided to identify a recipient and there a no matches an anonymous contact is created. This anonymous contact will prioritise email address over mobile number.

For example:

{
  "EmailAddress": "[email protected]",
  "MobileNumber": "07700900123"
}

This request will first attempt to find a contact based on the email address and then on the mobile number. If there are no matches an anonymous contact will be created preferring email and disregarding SMS content in some situations:

Payload Content	Recipient Detail	Anonymous Contact	Message Sent
Email and SMS	Email and Mobile	Email	Email
Email and SMS	Email	Email	Email
Email and SMS	Mobile	Mobile	SMS
Email	Email and Mobile	Email	Email
Email	Email	Email	Email
Email	Mobile	None	None
SMS	Email and Mobile	Mobile	SMS
SMS	Email	None	None
SMS	Mobile	Mobile	SMS

Advanced Recipient Options

Send To Relationship

Control who receives the message when dealing with student-parent relationships:

{
  "IdaasId": "PL-12345",
  "SendTo": 1
}

Value	Target	Description
0	Self	Send directly to the specified contact (default)
1	Primary Parent	Send to the primary parent of the student
2	All Parents	Send to all parents of the student

Message Personalization

Dynamic Tokens

Use dynamic tokens to personalize messages with recipient-specific data:

{
  "IdaasId": "PL-12345",
  "DynamicTokens": {
    "$studentName$": "Emma Johnson",
    "$appointmentTime$": "2:30 PM",
    "$teacherName$": "Mr. Smith",
    "$className$": "Year 7 Mathematics"
  }
}

Message Template Example:

"Hello! This is a reminder that $studentName$ has an appointment with $teacherName$ for $className$ at $appointmentTime$."

Rendered Message:

"Hello! This is a reminder that Emma Johnson has an appointment with Mr. Smith for Year 7 Mathematics at 2:30 PM."