Skip to main content
POST
This operation uses the live messaging service and can consume message credits. Use an approved Sender ID and message only recipients you are permitted to contact.
sendAt is always interpreted as Irish local time (Europe/Dublin). Do not include Z or a numeric UTC offset. For example, 2030-07-08T15:00 schedules delivery for 15:00 in Ireland, regardless of where the request originates. Convert the intended time to Irish local time before sending the request.

​
Scheduling from outside Ireland

Phonovation does not use your device, server, account, or recipient timezone. It reads the date and clock time in sendAt as the time in Ireland. Prefer yyyy-MM-ddTHH:mm. A space instead of T and optional seconds are also accepted. Supplied seconds are ignored, and the campaign is scheduled at the start of the minute. Use the IANA timezone Europe/Dublin in your date-time library. Do not hard-code an offset: Ireland changes offset during the year, and other countries may change clocks on different dates.
Omit sendAt or send null to send immediately. Empty and whitespace-only strings are invalid.

Authorizations

​
Authorization
string
header
required

A UI-generated Phonovation Personal Access Token (PAT) is the recommended option for most integrations. OAuth/OIDC JWT access tokens are also accepted when an OAuth lifecycle is required.

Send either token as:

Authorization: Bearer <token>

PAT values begin with phv_pat_. Generate a PAT once in the Phonovation UI, store it securely, and reuse it across requests. You do not need to generate or refresh a token for every SMS. Preserve the exact casing in Bearer phv_pat_....

Body

application/json

The message, sender, recipients, and optional campaign settings. Any sendAt value must contain the intended Irish local date and time.

Everything Phonovation needs to create, schedule, or save an SMS campaign.

​
text
string
required

The message your recipients will receive. It must include at least one visible character.

Phonovation automatically detects the message encoding and calculates how many SMS parts will be sent and billed:

  • GSM-7: up to 160 characters in one part, then 153 per part.
  • UTF-16: up to 70 characters in one part, then 67 per part.
  • GSM-7 extended characters count as two character units.

To improve handset compatibility, Phonovation replaces these typographic characters before sending:

  • typographic single quotes to '
  • typographic double quotes to "
  • en/em dashes to -
  • ellipsis to .
  • bullet to *

The API does not automatically add opt-out or footer text, so include any wording required for your use case and compliance obligations.

Required string length: 1 - 2000
Pattern: \S
Example:

"Your appointment is tomorrow at 10:30."

​
from
string
required

The sender name or number recipients see on their phone.

Leading and trailing spaces are removed automatically.

  • Numbers-only sender IDs may contain up to 20 digits.
  • All other sender IDs may contain up to 11 characters.
  • Numbers from 50000 through 59999 are reserved and cannot be used.

Non-numeric sender IDs are not limited to letters and numbers by this API.

For Irish recipients, the sender ID must be on the permitted sender list. Recipients for whom the sender is not permitted are skipped.

Minimum string length: 1
Pattern: \S
Example:

"CompanyName"

​
recipientInfo
Campaign Recipient · object[]
required

One or more people who should receive the campaign. The API does not set a maximum recipient count.

Invalid or duplicate numbers may be skipped while valid recipients continue. Duplicate detection happens after phone-number normalization, and the first occurrence is kept.

Minimum array length: 1
​
campaignName
string
default:API Broadcast

A short name to help you identify the campaign in reporting. If omitted, it defaults to API Broadcast.

Keep the name to 30 characters or fewer. null, empty, and spaces-only values are rejected. Valid names are stored exactly as supplied.

Required string length: 1 - 30
Pattern: \S
Example:

"Summer Promotion"

​
sendAt
string | null

When the campaign should be sent, interpreted exclusively as Irish local time in the Europe/Dublin timezone.

Phonovation reads the date and clock portion exactly as Irish time. It does not use the timezone of the caller, server, account, or recipient, and it does not convert the value from UTC. A request sent from China with 2030-07-08T15:00 schedules the campaign for 15:00 in Ireland, not 15:00 in China.

Prefer yyyy-MM-ddTHH:mm, for example 2030-07-08T14:30. These forms are accepted:

  • yyyy-MM-ddTHH:mm
  • yyyy-MM-ddTHH:mm:ss
  • yyyy-MM-dd HH:mm
  • yyyy-MM-dd HH:mm:ss

If seconds are supplied, they are ignored and the scheduled time is normalized to the start of the minute.

Example conversions for 8 July 2030 at 15:00 in the source country:

  • United Kingdom (Europe/London) becomes 2030-07-08T15:00 in Ireland.

  • China (Asia/Shanghai) becomes 2030-07-08T08:00 in Ireland.

  • New York, United States (America/New_York) becomes 2030-07-08T20:00 in Ireland.

  • Do not include Z, another timezone designator, or a numeric UTC offset.

  • If the intended send time is outside Ireland, convert it to Europe/Dublin before constructing this value.

  • Ireland uses GMT (UTC+0) during part of the year and Irish Standard Time (UTC+1) during part of the year. Use a timezone-aware library; do not hard-code a single UTC offset.

  • Omit the field or send null to send immediately. Empty and whitespace-only strings are invalid.

  • Past dates are accepted.

  • The API does not set a maximum scheduling horizon.

Pattern: ^\d{4}-\d{2}-\d{2}[T ]\d{2}:\d{2}(:\d{2})?$
Examples:

"2030-07-08T14:30"

"2030-07-08T14:30:45"

"2030-07-08 14:30"

"2030-07-08 14:30:45"

​
createAsDraft
boolean
default:false

Set to true to save the campaign as a draft. A draft has no delivery summary until it is marked ready.

​
shouldSaveList
boolean
default:false

Optional saved-list flag. It is passed through as shouldSaveList and defaults to false. Saved-list behaviour is not part of the current public API contract, so leave this as false unless Phonovation has enabled the feature for your integration.

Response

The campaign is accepted for background processing.

Confirms that the campaign request was accepted and queued.

​
id
string<uuid>
required

Public campaign UUID. Store it so you can request delivery totals later.

Example:

"ffd14db7-e526-4d69-b41e-ec5e38bc04dd"

​
message
string
required

Human-readable confirmation for logs or troubleshooting. A successful 202 response returns Campaign received to be processed.

Allowed value: "Campaign received to be processed"
Example:

"Campaign received to be processed"