To get full access to the Kademi Hub existing customers can login here, or new customers can register here.
One outbound SMS message: who it is going to, what it says, and how far the SMS provider has got with sending it. An SmsItem is created either by a group SMS job, by an email trigger sending over the SMS channel, or directly by application code, and is picked up by the sending job while its send status is not one of the finished states. The send status holds one of the short codes on the nested SmsStatus class, and the human readable version of it is the status text. Each attempt to hand the message to the provider is recorded as a child SmsSendAttempt, and any replies received back are child SmsReplyItem records. The cost the provider charged is copied onto the item once the provider reports it, and is billed to the billing organisation rather than the sending one.
Group: Database Entities
Implements: Serializable, Relational
Properties
| Property | Returns | Description |
|---|---|---|
| billingOrg | Organisation | The organisation which pays for this message, taken from the SMS settings. It is often a parent of the sending organisation, because SMS provider accounts are usually held higher up the hierarchy than the account which sends. |
| costAmount | BigDecimal | What the provider charged for sending this message, in the cost currency. Null until the provider has reported a cost, and note a long message can be charged as several parts. |
| costCurrency | String | The currency the provider charged for this message in. Null until the provider has reported a cost. |
| createdDate | Date | When the message was queued. The sending job ignores messages created more than seven days ago, so an item left unsent for longer than that is never picked up again. |
| emailTrigger | EmailTrigger | The trigger which generated this message, when it was sent by an email trigger configured to use the SMS channel. Null for messages from a group SMS job or created directly. |
| groupSmsJob | GroupSmsJob | The bulk send this message was part of, when it was generated by a group SMS job. Null for messages from a trigger or created directly. |
| id | long | Unique identifier for this SMS message, assigned by the database when the row is first saved. |
| lastAttempt | SmsSendAttempt | The most recent entry in this message's send attempts, which carries the status code and description the provider last returned. Null when the send attempts have not been set at all. |
| msgId | String | The provider's own identifier for the message, stored once it has been accepted for sending, and used to match up delivery receipts and replies. Null until the message has been handed to the provider. |
| nextAttempt | Date | The time the next send attempt is scheduled for after a retryable failure. Null when no retry has been scheduled. |
| numAttempts | Integer | How many times sending has been attempted so far. Null before the first attempt, and reset back to null when the message is reset for resending. |
| phoneToUse | String | The number this message should actually be sent to: the recipient phone recorded on the message if one was given, otherwise the phone number on the recipient profile. Throws if the message has neither a recipient phone nor a recipient profile. |
| providerAppId | String | Identifies which SMS provider the message is sent through, taken from the job or trigger that created it. |
| providerUsername | String | The username of the SMS provider account the message is sent through, copied from the SMS settings when the message is created so a later settings change does not rewrite history. |
| recipientPhone | String | The phone number to send to, when it was captured on the message itself rather than read from the recipient profile. Usually null, in which case the recipient profile's phone number is used instead. |
| sendAttempts | List<SmsSendAttempt> | Every attempt made to hand this message to the provider, each with the status code and description the provider returned. Empty or null when no attempt has been made yet. |
| sendingOrg | Organisation | The organisation the message was sent on behalf of, ie the account whose job or trigger created it. Message searches and listings are scoped by it. |
| sendStatus | String | Where the message is up to, as one of the short codes on the nested SmsStatus class, eg i for idle, s for sent, d for delivered and f for failed. The sending job only picks up messages which are not sent, sending, delivered, failed or without a phone number. |
| sendStatusDate | Date | When the send status last changed, ie when the message was last attempted or when a delivery receipt was last applied. |
| smsMsg | String | The message text as it will be sent, already merged from its template, limited to 1000 characters. Anything longer than a single SMS is charged by the provider as multiple parts. |
| smsRecipient | Profile | The profile the message is addressed to. The number actually dialled is the recipient phone if one was set on the message, otherwise this profile's phone number; use getPhoneToUse to get whichever applies. |
| smsReplies | List<SmsReplyItem> | Replies received back from the recipient which the provider matched to this message. Empty or null if there have been no replies. |
| smsSender | String | The sender the message is presented as coming from, taken from the SMS settings when the message is created. Depending on the provider and the country this is either a phone number or an alphanumeric sender ID. |
| statusText | String | Human readable explanation of the send status, such as the provider's rejection reason for a failed message. Shown to administrators alongside the status code. |
Methods
getId() · getSmsRecipient() · getSmsSender() · getSmsMsg() · getRecipientPhone() · getSendingOrg() · getBillingOrg() · getProviderUsername() · getProviderAppId() · getMsgId() · getSendStatus() · getStatusText() · getCreatedDate() · getSendStatusDate() · getNumAttempts() · getNextAttempt() · getEmailTrigger() · getGroupSmsJob() · getCostCurrency() · getCostAmount() · getSendAttempts() · getSmsReplies() · getLastAttempt() · getPhoneToUse()
getId()
Returns: long
Unique identifier for this SMS message, assigned by the database when the row is first saved.
getSmsRecipient()
Returns: Profile
The profile the message is addressed to. The number actually dialled is the recipient phone if one was set on the message, otherwise this profile's phone number; use getPhoneToUse to get whichever applies.
getSmsSender()
Returns: String
The sender the message is presented as coming from, taken from the SMS settings when the message is created. Depending on the provider and the country this is either a phone number or an alphanumeric sender ID.
getSmsMsg()
Returns: String
The message text as it will be sent, already merged from its template, limited to 1000 characters. Anything longer than a single SMS is charged by the provider as multiple parts.
getRecipientPhone()
Returns: String
The phone number to send to, when it was captured on the message itself rather than read from the recipient profile. Usually null, in which case the recipient profile's phone number is used instead.
getSendingOrg()
Returns: Organisation
The organisation the message was sent on behalf of, ie the account whose job or trigger created it. Message searches and listings are scoped by it.
getBillingOrg()
Returns: Organisation
The organisation which pays for this message, taken from the SMS settings. It is often a parent of the sending organisation, because SMS provider accounts are usually held higher up the hierarchy than the account which sends.
getProviderUsername()
Returns: String
The username of the SMS provider account the message is sent through, copied from the SMS settings when the message is created so a later settings change does not rewrite history.
getProviderAppId()
Returns: String
Identifies which SMS provider the message is sent through, taken from the job or trigger that created it.
getMsgId()
Returns: String
The provider's own identifier for the message, stored once it has been accepted for sending, and used to match up delivery receipts and replies. Null until the message has been handed to the provider.
getSendStatus()
Returns: String
Where the message is up to, as one of the short codes on the nested SmsStatus class, eg i for idle, s for sent, d for delivered and f for failed. The sending job only picks up messages which are not sent, sending, delivered, failed or without a phone number.
getStatusText()
Returns: String
Human readable explanation of the send status, such as the provider's rejection reason for a failed message. Shown to administrators alongside the status code.
getCreatedDate()
Returns: Date
When the message was queued. The sending job ignores messages created more than seven days ago, so an item left unsent for longer than that is never picked up again.
getSendStatusDate()
Returns: Date
When the send status last changed, ie when the message was last attempted or when a delivery receipt was last applied.
getNumAttempts()
Returns: Integer
How many times sending has been attempted so far. Null before the first attempt, and reset back to null when the message is reset for resending.
getNextAttempt()
Returns: Date
The time the next send attempt is scheduled for after a retryable failure. Null when no retry has been scheduled.
getEmailTrigger()
Returns: EmailTrigger
The trigger which generated this message, when it was sent by an email trigger configured to use the SMS channel. Null for messages from a group SMS job or created directly.
getGroupSmsJob()
Returns: GroupSmsJob
The bulk send this message was part of, when it was generated by a group SMS job. Null for messages from a trigger or created directly.
getCostCurrency()
Returns: String
The currency the provider charged for this message in. Null until the provider has reported a cost.
getCostAmount()
Returns: BigDecimal
What the provider charged for sending this message, in the cost currency. Null until the provider has reported a cost, and note a long message can be charged as several parts.
getSendAttempts()
Returns: List<SmsSendAttempt>
Every attempt made to hand this message to the provider, each with the status code and description the provider returned. Empty or null when no attempt has been made yet.
getSmsReplies()
Returns: List<SmsReplyItem>
Replies received back from the recipient which the provider matched to this message. Empty or null if there have been no replies.
getLastAttempt()
Returns: SmsSendAttempt
The most recent entry in this message's send attempts, which carries the status code and description the provider last returned. Null when the send attempts have not been set at all.
getPhoneToUse()
Returns: String
The number this message should actually be sent to: the recipient phone recorded on the message if one was given, otherwise the phone number on the recipient profile. Throws if the message has neither a recipient phone nor a recipient profile.
© 2025 Kademi Ltd