---
title: "Create a message"
method: POST
path: "/accounts/{account_id}/messages"
tags: ["Messages"]
---

# Create a message

`POST /accounts/{account_id}/messages`

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"`.

## Path parameters

- `account_id` string, required — The account from which the message should be sent.

## Request body

- union — Payload for creating a message. Either an attachment or the body must be given. You can specify the recipient either using the 'conversation' parameter or the 'to'/'from' parameters, but not both.
  - object — Create a message while including parameters for the conversation in which the message should be sent.
    - `attachments` AttachmentParams[]
      - `url` string, required — The URL of the attachment.
    - `body` string — The message body.
    - `conversation` ConversationParams, required — Params for selecting or creating a new conversation. Either the id or the Contact must be given.
      - `contact` ContactParams, required — Parameters for creating a contact
        - `email` string, email — The contact's email address.
        - `first_name` string — The contact's first name.
        - `last_name` string — The contact's last name.
        - `metadata` Metadata — Set of key-value pairs that will be stored with the object.
        - `phone_number` string, phone-number, required — The contact's phone number in E.164 format.
      - `phone_number` string — The phone number from which to send the message. This can be either the phone number in E.164 format or a Surge phone number id.
    - `metadata` Metadata — Set of key-value pairs that will be stored with the object.
    - `send_at` string, date-time — An optional datetime for scheduling message up to a couple of months in the future.
    - `settings` MessageSettingsParams — Per-message setting overrides.
      - `link_shortening` 'enabled' | 'disabled' — Override link shortening for this message.
  - object — Create a basic message by specifying just the to/from phone numbers.
    - `attachments` AttachmentParams[]
      - `url` string, required — The URL of the attachment.
    - `body` string — The message body.
    - `from` string — The sender's phone number in E.164 format or phone number ID. If omitted, uses the account's default phone number. Cannot be used together with 'conversation'.
    - `metadata` Metadata — Set of key-value pairs that will be stored with the object.
    - `send_at` string, date-time — An optional datetime for scheduling message up to a couple of months in the future.
    - `settings` MessageSettingsParams — Per-message setting overrides.
      - `link_shortening` 'enabled' | 'disabled' — Override link shortening for this message.
    - `to` string, phone-number, required — The recipient's phone number in E.164 format. Cannot be used together with 'conversation'.

## Response `201`

Created message

- Message — A Message is a communication sent to a Contact.
  - `attachments` Attachment[]
    - `id` string — Unique identifier for the object.
    - `type` 'file' | 'image' | 'link' | 'contact' | 'video' — The type of attachment.
    - `url` string — The URL of the attachment.
  - `blast_id` string, nullable — The ID of the blast this message belongs to, if any. This can be used to attribute messages back to a specific blast.
  - `body` string, nullable — The message body.
  - `conversation` Conversation — A conversation with a Contact
    - `contact` Contact, required — A contact who has consented to receive messages
      - `email` string, email — The contact's email address.
      - `first_name` string — The contact's first name.
      - `id` string, required — Unique identifier for the object.
      - `last_name` string — The contact's last name.
      - `metadata` Metadata — Set of key-value pairs that will be stored with the object.
      - `phone_number` string, phone-number, required — The contact's phone number in E.164 format.
    - `id` string, required — Unique identifier for the object.
    - `phone_number` ConversationPhoneNumber — This is the phone number tied to the Surge account.
      - `id` string, required — Unique identifier for the phone number
      - `name` string, nullable, required — A human-readable name for the phone number
      - `number` string, phone-number, required — The canonical format of the phone number.
      - `type` 'local' | 'toll_free' | 'short_code' | 'demo', required — Whether the phone number is local, toll-free, or short code
  - `id` string — Unique identifier for the object.
  - `metadata` Metadata — Set of key-value pairs that will be stored with the object.

## Other responses

- `default` — Error

---

[API](https://skmtc.net/surgeapi/apis/surge.md) · [All operations](https://skmtc.net/surgeapi/apis/surge/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/surgeapi/surge/revisions/b5b0b6f62245/schema)