Skip to main content

Recipients Reference

The Recipients field is used across all Communications API endpoints (SMS, Email, PartnerRoute) 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": [
    {
      "MobileNumber": "+447700900123"
    },
    {
      "EmailAddress": "[email protected]"
    }
  ]
}

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. Contact ID (Highest Priority)​

{
  "Id": 12345
}
  • Type: Integer
  • Description: Direct reference to an existing contact in the system
  • Usage: When you have the internal contact ID
  • Priority: #1 - Used if Id > 0

2. External ID​

{
  "ExternalId": "STUDENT_001_PARENT_A"
}
  • Type: String
  • Description: Your system's unique identifier for the contact
  • Usage: When integrating with external systems that maintain their own contact IDs
  • Priority: #2

3. Messenger ID​

{
  "MessengerId": "msg_contact_abc123"
}
  • Type: String
  • Description: Unique identifier from the Messenger system
  • Usage: When sending through Messenger integrations
  • Priority: #3

4. IDaaS ID​

{
  "IdaasId": "idaas_user_xyz789"
}
  • Type: String
  • Description: Identity as a Service unique identifier
  • Usage: When using IDaaS authentication systems
  • Priority: #4

5. 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
  • Priority: #5 - Looks up in addresses table, then ExternalId, then creates new contact

6. Mobile Number​

{
  "MobileNumber": "+447700900123"
}
  • Type: String (International format)
  • Description: Mobile phone number for contact lookup and SMS delivery
  • Usage: For SMS messages or contact lookup by phone number
  • Priority: #6 - Looks up in addresses table, then ExternalId, then creates new contact

Contact Generation​

When a recipient cannot be found using the identification methods above, the system can generate a new contact using the provided name information:

{
  "MobileNumber": "+447700900123",
  "Forename": "Sarah",
  "Surname": "Johnson"
}

Name Fields​

  • Forename (String): First name for generated contacts
  • Surname (String): Last name for generated contacts

Advanced Recipient Options​

Send To Relationship​

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

{
  "MobileNumber": "+447700900123",
  "SendTo": 1
}
ValueTargetDescription
0SelfSend directly to the specified contact (default)
1Primary ParentSend to the primary parent of the student
2All ParentsSend to all parents of the student
Storage Detail

The SendTo value is stored in the PhotoURL field in the system.

Email Location Type​

Specify which email address to use when multiple are available:

{
  "EmailAddress": "[email protected]",
  "EmailLocationType": "Home"
}
ValueDescription
"Work"Use work email address
"Home"Use home email address
Storage Detail

The EmailLocationType value is stored in the AttendanceMarks field in the system.

Message Personalization​

Dynamic Tokens​

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

{
  "MobileNumber": "+447700900123",
  "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."

Student Context Messages​

Send messages "regarding" a specific student by providing student identification. This is useful for parent notifications about their children:

Student Contact ID​

{
  "MobileNumber": "+447700900123",
  "StudentId": "67890"
}

Student External ID​

{
  "MobileNumber": "+447700900123",
  "StudentExternalId": "STUDENT_001"
}

Student Messenger ID​

{
  "MobileNumber": "+447700900123",
  "StudentMessengerId": "msg_student_abc123"
}

Student IDaaS ID​

{
  "MobileNumber": "+447700900123",
  "StudentIdaasId": "idaas_student_xyz789"
}

Complete Examples​

Simple SMS to Known Contact​

{
  "Recipients": [
    {
      "MobileNumber": "+447700900123"
    }
  ]
}

Email with Dynamic Personalization​

{
  "Recipients": [
    {
      "EmailAddress": "[email protected]",
      "DynamicTokens": {
        "parentName": "Mrs. Johnson",
        "studentName": "Emma",
        "eventDate": "Tuesday, July 16th"
      }
    }
  ]
}
{
  "Recipients": [
    {
      "ExternalId": "PARENT_001",
      "SendTo": 1,
      "StudentExternalId": "STUDENT_001",
      "DynamicTokens": {
        "studentName": "Emma Johnson",
        "subject": "Mathematics",
        "grade": "A+"
      }
    }
  ]
}

Multiple Contact Methods with Fallback​

{
  "Recipients": [
    {
      "Id": 12345,
      "ExternalId": "CONTACT_001",
      "MobileNumber": "+447700900123",
      "EmailAddress": "[email protected]",
      "Forename": "Sarah",
      "Surname": "Johnson"
    }
  ]
}

Work Email with Student Context​

{
  "Recipients": [
    {
      "EmailAddress": "[email protected]",
      "EmailLocationType": "Work",
      "StudentExternalId": "STUDENT_001",
      "DynamicTokens": {
        "studentName": "Emma Johnson",
        "message": "parent-teacher conference"
      }
    }
  ]
}

Best Practices​

Identification Strategy​

  1. Use Contact IDs when available - Most efficient for known contacts
  2. Implement External ID mapping - Maintain your own contact reference system
  3. Provide fallback information - Include name fields for contact generation
  4. Validate phone/email formats - Ensure proper international format for phones

Personalization Guidelines​

  1. Keep tokens simple - Use clear, descriptive token names
  2. Validate token data - Ensure all tokens have values before sending
  3. Test with sample data - Verify message rendering with real data
  4. Consider character limits - Account for expanded token content in SMS

Performance Optimization​

  1. Batch similar recipients - Group messages with similar token sets
  2. Pre-validate contacts - Check contact existence before bulk operations
  3. Use appropriate identification - Choose the most efficient lookup method
  4. Monitor delivery rates - Track success rates by identification method

Integration Patterns​

External System Integration​

// Map your system contacts to API recipients
const recipients = externalContacts.map(contact => ({
  ExternalId: contact.id,
  MobileNumber: contact.phone,
  EmailAddress: contact.email,
  Forename: contact.firstName,
  Surname: contact.lastName,
  DynamicTokens: {
    customerName: contact.fullName,
    accountNumber: contact.accountId
  }
}));

Student Information System Integration​

// Send to all parents of students in a class
const recipients = students.map(student => ({
  StudentExternalId: student.id,
  SendTo: 2, // All parents
  DynamicTokens: {
    studentName: student.fullName,
    className: student.currentClass,
    teacherName: student.teacher
  }
}));

Related Documentation: