> ## Documentation Index
> Fetch the complete documentation index at: https://docs.surge.app/llms.txt
> Use this file to discover all available pages before exploring further.

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




## OpenAPI

````yaml POST /accounts/{account_id}/messages
openapi: 3.1.1
info:
  title: Surge
  version: '1.0'
servers:
  - url: https://api.surge.app
security:
  - authorization: []
paths:
  /accounts/{account_id}/messages:
    post:
      tags:
        - Messages
      summary: Create a message
      description: >
        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"`.
      operationId: CreateMessage
      parameters:
        - in: path
          name: account_id
          required: true
          schema:
            description: The account from which the message should be sent.
            example: acct_01j9a43avnfqzbjfch6pygv1td
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MessageParams'
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Message'
          description: Created message
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Error
      x-codeSamples:
        - lang: JavaScript
          source: >-
            import Surge from '@surgeapi/node';


            const client = new Surge({
              apiKey: process.env['SURGE_API_KEY'], // This is the default and can be omitted
            });


            const message = await
            client.messages.create('acct_01j9a43avnfqzbjfch6pygv1td', {
              conversation: { contact: { phone_number: '+18015551234' } },
            });


            console.log(message.id);
        - lang: Python
          source: |-
            import os
            from surge import Surge

            client = Surge(
                api_key=os.environ.get("SURGE_API_KEY"),  # This is the default and can be omitted
            )
            message = client.messages.create(
                account_id="acct_01j9a43avnfqzbjfch6pygv1td",
                conversation={
                    "contact": {
                        "phone_number": "+18015551234"
                    }
                },
            )
            print(message.id)
        - lang: Go
          source: "package main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\n\t\"github.com/stainless-sdks/surge-go\"\n\t\"github.com/stainless-sdks/surge-go/option\"\n)\n\nfunc main() {\n\tclient := surge.NewClient(\n\t\toption.WithAPIKey(\"My API Key\"),\n\t)\n\tmessage, err := client.Messages.New(\n\t\tcontext.TODO(),\n\t\t\"acct_01j9a43avnfqzbjfch6pygv1td\",\n\t\tsurge.MessageNewParams{\n\t\t\tOfMessagesWithConversation: &surge.MessageNewParamsMessageParamsMessageParamsWithConversation{\n\t\t\t\tConversation: surge.MessageNewParamsMessageParamsMessageParamsWithConversationConversation{\n\t\t\t\t\tContact: surge.MessageNewParamsMessageParamsMessageParamsWithConversationConversationContact{\n\t\t\t\t\t\tPhoneNumber: \"+18015551234\",\n\t\t\t\t\t},\n\t\t\t\t},\n\t\t\t},\n\t\t},\n\t)\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf(\"%+v\\n\", message.ID)\n}\n"
        - lang: Ruby
          source: |-
            require "surge_api"

            surge = SurgeAPI::Client.new(api_key: "My API Key")

            message = surge.messages.create(
              "acct_01j9a43avnfqzbjfch6pygv1td",
              message_params: {conversation: {contact: {phone_number: "+18015551234"}}}
            )

            puts(message)
        - lang: PHP
          source: >-
            <?php


            require_once dirname(__DIR__) . '/vendor/autoload.php';


            use Surge\Client;

            use Surge\Core\Exceptions\APIException;


            $client = new Client(apiKey: getenv('SURGE_API_KEY') ?: 'My API
            Key');


            try {
              $message = $client->messages->create(
                'acct_01j9a43avnfqzbjfch6pygv1td',
                conversation: [
                  'contact' => [
                    'phoneNumber' => '+18015551234',
                    'email' => 'dom@toretto.family',
                    'firstName' => 'Dominic',
                    'lastName' => 'Toretto',
                    'metadata' => ['car' => '1970 Dodge Charger R/T'],
                  ],
                  'phoneNumber' => '+18015556789',
                ],
                attachments: [['url' => 'https://toretto.family/coronas.gif']],
                body: 'body',
                metadata: ['foo' => 'string'],
                sendAt: new \DateTimeImmutable('2019-12-27T18:11:19.117Z'),
                settings: ['linkShortening' => 'enabled'],
                to: '+18015551234',
                from: '+18015552345',
              );

              var_dump($message);
            } catch (APIException $e) {
              echo $e->getMessage();
            }
components:
  schemas:
    MessageParams:
      description: >-
        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.
      example:
        attachments:
          - url: https://toretto.family/coronas.gif
        body: Thought you could leave without saying goodbye?
        conversation:
          contact:
            first_name: Dominic
            last_name: Toretto
            phone_number: '+18015551234'
        metadata:
          external_id: '12345'
        settings:
          link_shortening: enabled
      oneOf:
        - description: >-
            Create a message while including parameters for the conversation in
            which the message should be sent.
          properties:
            attachments:
              items:
                $ref: '#/components/schemas/AttachmentParams'
              type: array
            body:
              description: The message body.
              type: string
            conversation:
              $ref: '#/components/schemas/ConversationParams'
            metadata:
              $ref: '#/components/schemas/Metadata'
            send_at:
              description: >-
                An optional datetime for scheduling message up to a couple of
                months in the future.
              format: date-time
              type: string
            settings:
              $ref: '#/components/schemas/MessageSettingsParams'
          required:
            - conversation
          title: MessageParamsWithConversation
          type: object
        - description: Create a basic message by specifying just the to/from phone numbers.
          properties:
            attachments:
              items:
                $ref: '#/components/schemas/AttachmentParams'
              type: array
            body:
              description: The message body.
              type: string
            from:
              description: >-
                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'.
              example: '+18015552345'
              pattern: ^\+[1-9]\d{6,14}$|^\d{5,6}$|^pn_[[:alnum:]]{26}$
              type: string
            metadata:
              $ref: '#/components/schemas/Metadata'
            send_at:
              description: >-
                An optional datetime for scheduling message up to a couple of
                months in the future.
              format: date-time
              type: string
            settings:
              $ref: '#/components/schemas/MessageSettingsParams'
            to:
              description: >-
                The recipient's phone number in E.164 format. Cannot be used
                together with 'conversation'.
              example: '+18015551234'
              format: phone-number
              pattern: ^\+[1-9]\d{6,14}$
              type: string
          required:
            - to
          title: SimpleMessageParams
          type: object
      title: MessageParams
      type: object
    Message:
      description: A Message is a communication sent to a Contact.
      example:
        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'
      properties:
        attachments:
          items:
            $ref: '#/components/schemas/Attachment'
          type: array
        blast_id:
          description: >-
            The ID of the blast this message belongs to, if any. This can be
            used to attribute messages back to a specific blast.
          type:
            - string
            - 'null'
        body:
          description: The message body.
          type:
            - string
            - 'null'
        conversation:
          $ref: '#/components/schemas/Conversation'
        id:
          description: Unique identifier for the object.
          type: string
        metadata:
          $ref: '#/components/schemas/Metadata'
      title: Message
      type: object
    ErrorResponse:
      description: An error response
      example:
        error:
          message: The requested resource could not be found.
          type: not_found
      properties:
        error:
          $ref: '#/components/schemas/Error'
      required:
        - error
      title: ErrorResponse
      type: object
    AttachmentParams:
      description: Params for creating an attachment
      example:
        url: https://toretto.family/coronas.gif
      properties:
        url:
          description: The URL of the attachment.
          type: string
      required:
        - url
      title: AttachmentParams
      type: object
    ConversationParams:
      description: >-
        Params for selecting or creating a new conversation. Either the id or
        the Contact must be given.
      example:
        contact:
          first_name: Dominic
          last_name: Toretto
          phone_number: '+18015551234'
        phone_number: '+18015556789'
      properties:
        contact:
          $ref: '#/components/schemas/ContactParams'
        phone_number:
          description: >-
            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.
          example: '+18015552345'
          pattern: ^\+[1-9]\d{6,14}$|^\d{5,6}$|^pn_[[:alnum:]]{26}$
          type: string
      required:
        - contact
      title: ConversationParams
      type: object
    Metadata:
      additionalProperties:
        maxLength: 500
        type: string
      description: Set of key-value pairs that will be stored with the object.
      maxProperties: 50
      properties: {}
      title: Metadata
      type: object
    MessageSettingsParams:
      description: Per-message setting overrides.
      example:
        link_shortening: enabled
      properties:
        link_shortening:
          description: Override link shortening for this message.
          enum:
            - enabled
            - disabled
          type: string
      title: MessageSettingsParams
      type: object
    Attachment:
      description: An Attachment is a file that can be sent with a message.
      example:
        id: att_01j9e0m1m6fc38gsv2vkfqgzz2
        type: image
        url: https://api.surge.app/attachments/att_01jbwyqj7rejzat7pq03r7fgmf
      properties:
        id:
          description: Unique identifier for the object.
          type: string
        type:
          description: The type of attachment.
          enum:
            - file
            - image
            - link
            - contact
            - video
          type: string
        url:
          description: The URL of the attachment.
          type: string
      title: Attachment
      type: object
    Conversation:
      description: A conversation with a Contact
      example:
        contact:
          first_name: Dominic
          id: ctc_01j9dy8mdzfn3r0e8x1tbdrdrf
          last_name: Toretto
          phone_number: '+18015551234'
        id: cnv_01j9e0dgmdfkj86c877ws0znae
        phone_number:
          id: pn_01jsjwe4d9fx3tpymgtg958d9w
          name: (801) 555-2345
          number: '+18015552345'
          type: local
      properties:
        contact:
          $ref: '#/components/schemas/Contact'
        id:
          description: Unique identifier for the object.
          type: string
        phone_number:
          $ref: '#/components/schemas/ConversationPhoneNumber'
      required:
        - id
        - contact
      title: Conversation
      type: object
    Error:
      description: An error response
      example:
        message: The requested resource was not found.
        type: not_found
      properties:
        detail:
          additionalProperties: true
          description: Additional details about the error.
          type: object
        message:
          description: A human-readable error message.
          example: The requested resource was not found.
          type: string
        type:
          description: A unique error code.
          example: not_found
          type: string
      required:
        - type
        - message
      title: Error
      type: object
    ContactParams:
      description: Parameters for creating a contact
      example:
        email: dom@toretto.family
        first_name: Dominic
        last_name: Toretto
        metadata:
          car: 1970 Dodge Charger R/T
        phone_number: '+18015551234'
      properties:
        email:
          description: The contact's email address.
          format: email
          type: string
        first_name:
          description: The contact's first name.
          type: string
        last_name:
          description: The contact's last name.
          type: string
        metadata:
          $ref: '#/components/schemas/Metadata'
        phone_number:
          description: The contact's phone number in E.164 format.
          example: '+18015551234'
          format: phone-number
          pattern: ^\+[1-9]\d{6,14}$
          type: string
      required:
        - phone_number
      title: ContactParams
      type: object
    Contact:
      description: A contact who has consented to receive messages
      example:
        email: dom@toretto.family
        first_name: Dominic
        id: ctc_01j9dy8mdzfn3r0e8x1tbdrdrf
        last_name: Toretto
        metadata:
          car: 1970 Dodge Charger R/T
        phone_number: '+18015551234'
      properties:
        email:
          description: The contact's email address.
          format: email
          type: string
        first_name:
          description: The contact's first name.
          type: string
        id:
          description: Unique identifier for the object.
          type: string
        last_name:
          description: The contact's last name.
          type: string
        metadata:
          $ref: '#/components/schemas/Metadata'
        phone_number:
          description: The contact's phone number in E.164 format.
          example: '+18015551234'
          format: phone-number
          pattern: ^\+[1-9]\d{6,14}$
          type: string
      required:
        - id
        - phone_number
      title: Contact
      type: object
    ConversationPhoneNumber:
      description: This is the phone number tied to the Surge account.
      example:
        id: pn_01jsjwe4d9fx3tpymgtg958d9w
        name: (801) 555-1234
        number: '+18015551234'
        type: local
      properties:
        id:
          description: Unique identifier for the phone number
          type: string
        name:
          description: A human-readable name for the phone number
          type:
            - string
            - 'null'
        number:
          description: The canonical format of the phone number.
          example: '+18015551234'
          format: phone-number
          pattern: ^\+[1-9]\d{6,14}$|^\d{5,6}$
          type: string
        type:
          description: Whether the phone number is local, toll-free, or short code
          enum:
            - local
            - toll_free
            - short_code
            - demo
          type: string
      required:
        - id
        - name
        - number
        - type
      title: ConversationPhoneNumber
      type: object
  securitySchemes:
    authorization:
      bearerFormat: Surge API token
      scheme: bearer
      type: http

````