Messages

Create a message

Creates and enqueues a new message to be sent.

Messages are always sent asynchronously. When you hit this endpoint, the message will be created within Surge's system and enqueued for sending, and then the id for the new message will be returned. When the message is actually sent, a message.sent webhook event will be triggered and sent to any webhook endpoints that you have subscribed to this event type. Then a message.delivered webhook event will be triggered when the carrier sends us a delivery receipt.

By default all messages will be sent immediately. If you would like to schedule sending for some time up to 60 days in the future, you can do that by providing a value for the send_at field. This should be formatted as an ISO8601 datetime like 2028-10-14T18:06:00Z.

You must include either a body or attachments field (or both) in the request body. The body field should contain the text of the message you want to send, and the attachments field should be an array of objects with a url field pointing to the file you want to attach. Surge will download these files and send them as attachments in the message.

You can provide either a conversation object or a to field to specify the intended recipient of the message, but an error will be returned if both fields are provided. Similarly the from field cannot be used together with the conversation field, and conversation.phone_number should be specified instead.

Optionally, you can pass a settings object to override account-level settings for this message. Currently the only supported setting is link_shortening, which accepts "enabled" or "disabled".

post/accounts/{account_id}/messages

Path parameters

account_idstring required

The account from which the message should be sent.

Example:acct_01j9a43avnfqzbjfch6pygv1td

Request body

Example request

{
  "attachments": [
    {
      "url": "https://toretto.family/coronas.gif"
    }
  ],
  "conversation": {
    "contact": {
      "first_name": "Dominic",
      "last_name": "Toretto",
      "phone_number": "+18015551234"
    },
    "phone_number": "+18015556789"
  },
  "settings": {
    "link_shortening": "enabled"
  }
}

Response

Created message

blast_idstring nullable

The ID of the blast this message belongs to, if any. This can be used to attribute messages back to a specific blast.

bodystring nullable

The message body.

idstring

Unique identifier for the object.

metadataMetadata

Set of key-value pairs that will be stored with the object.

status'pending' | 'received' | 'sent' | 'delivered' | 'failed'

The current status of the message.

Example response

{
  "attachments": [
    {
      "id": "att_01j9e0m1m6fc38gsv2vkfqgzz2",
      "type": "image",
      "url": "https://api.surge.app/attachments/att_01jbwyqj7rejzat7pq03r7fgmf"
    }
  ],
  "blast_id": null,
  "body": "Thought you could leave without saying goodbye?",
  "conversation": {
    "contact": {
      "first_name": "Dominic",
      "id": "ctc_01j9dy8mdzfn3r0e8x1tbdrdrf",
      "last_name": "Toretto",
      "phone_number": "+18015551234"
    },
    "id": "cnv_01j9e0dgmdfkj86c877ws0znae",
    "phone_number": {
      "id": "pn_01jsjwe4d9fx3tpymgtg958d9w",
      "number": "+18015552345",
      "type": "local"
    }
  },
  "id": "msg_01j9e0m1m6fc38gsv2vkfqgzz2",
  "metadata": {
    "external_id": "12345"
  },
  "status": "delivered"
}

Changes

Changed in 10 of the 63 revisions of this API.2510

Sep 4, 202693f3909cbde31See the full diff
- ○
  added the optional property to the response with the status
  response-optional-property-added
Aug 19, 202633842756c9f92See the full diff
- ○
  added the new optional request property ///
  new-optional-request-property
- ○
  added the optional property // to the response with the status
  response-optional-property-added
Jun 30, 2026dfa41068bb2f2See the full diff
- ○
  added the new optional request property /
  new-optional-request-property
- ○
  added the new optional request property /
  new-optional-request-property
Jun 30, 20262dc9f9377d571See the full diff
- ●
  added the new contact enum value to the // response property for the response status
  response-property-enum-value-added
Apr 22, 2026844ecbfa0d5b1See the full diff
- ○
  added the required property // to the response with the status
  response-required-property-added
Feb 19, 20268e7818aeefab4See the full diff
- ●
  added the new file enum value to the // response property for the response status
  response-property-enum-value-added
- ●
  added the new image enum value to the // response property for the response status
  response-property-enum-value-added
- ●
  added the new link enum value to the // response property for the response status
  response-property-enum-value-added
- ●
  added the new video enum value to the // response property for the response status
  response-property-enum-value-added
Feb 12, 2026562a744933391See the full diff
- ▲
  the response property became nullable for the status
  response-property-became-nullable
Feb 1, 2026345fdd13af9e1See the full diff
- ▲
  the response property became nullable for the status
  response-property-became-nullable
This revision also has 1 change that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog
Jan 24, 202641034d1fa9481See the full diff
- ○
  added the optional property to the response with the status
  response-optional-property-added
Jan 18, 2026fd3efee5d0c83See the full diff
- ○
  added the new optional request property /
  new-optional-request-property
- ○
  added the new optional request property /
  new-optional-request-property
- ○
  added the optional property to the response with the status
  response-optional-property-added

Full history