Send SMS with Vonage through Courier

Prerequisites

A Vonage (formerly Nexmo) account
Your Vonage API key and API secret
An SMS-capable from number on that account

Setup

Get your Vonage API credentials

In Vonage, open secret management and copy your API key and API secret.

Configure in Courier

Open the in Courier, enter your API key, API secret, and from number, then save.

The catalog also lists Vonage (Nexmo) under the provider key nexmo. It takes the same API key, API secret, and from number, and sends the same way, so an integration already on nexmo keeps working and needs no migration. Use vonage for a new integration. It is the one that reports provider errors back to Courier.

Addressing a recipient and sending are the same on every SMS provider, so they are documented once: and .

Overrides

covers the two levels and which one wins. Overrides change the request body and config Courier sends to Vonage. In config, override apiKey, apiSecret, fromNumber, and url. In body, override any message field.

const { requestId } = await courier.send.message({
  message: {
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    to: {
      phone_number: "+12345678901",
    },
    providers: {
      vonage: {
        override: {
          body: {
            text: "Override message text",
          },
          config: {
            apiKey: "<override API key>",
            apiSecret: "<override API secret>",
            fromNumber: "<override from number>",
            url: "<alternate API url>",
          },
        },
      },
    },
  },
});

response = client.send.message(
    message={
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
        "to": {
            "phone_number": "+12345678901",
        },
        "providers": {
            "vonage": {
                "override": {
                    "body": {
                        "text": "Override message text",
                    },
                    "config": {
                        "apiKey": "<override API key>",
                        "apiSecret": "<override API secret>",
                        "fromNumber": "<override from number>",
                        "url": "<alternate API url>",
                    },
                },
            },
        },
    },
)

curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
      "to": {
        "phone_number": "+12345678901"
      },
      "providers": {
        "vonage": {
          "override": {
            "body": {
              "text": "Override message text"
            },
            "config": {
              "apiKey": "<override API key>",
              "apiSecret": "<override API secret>",
              "fromNumber": "<override from number>",
              "url": "<alternate API url>"
            }
          }
        }
      }
    }
  }'

response = courier.send_.message(
  message: {
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    to: {
      phone_number: "+12345678901"
    },
    providers: {
      vonage: {
        override: {
          body: {
            text: "Override message text"
          },
          config: {
            apiKey: "<override API key>",
            apiSecret: "<override API secret>",
            fromNumber: "<override from number>",
            url: "<alternate API url>"
          }
        }
      }
    }
  }
)

response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{
			OfUserRecipient: &shared.UserRecipientParam{
				PhoneNumber: courier.String("+12345678901"),
			},
		},
		Template: courier.String("nt_01kx4h2jdafq8bk9aftxak4b40"),
		Providers: shared.MessageProvidersParam{
			"vonage": shared.MessageProvidersTypeParam{
				Override: map[string]any{
					"body": map[string]any{
						"text": "Override message text",
					},
					"config": map[string]any{
						"apiKey": "<override API key>",
						"apiSecret": "<override API secret>",
						"fromNumber": "<override from number>",
						"url": "<alternate API url>",
					},
				},
			},
		},
	},
})

SendMessageParams params = SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        .to(UserRecipient.builder().phoneNumber("+12345678901").build())
        .template("nt_01kx4h2jdafq8bk9aftxak4b40")
        .providers(MessageProviders.builder()
            .putAdditionalProperty("vonage", JsonValue.from(java.util.Map.of("override", java.util.Map.of(
                    "body", java.util.Map.of(
                        "text", "Override message text"
                    ),
                    "config", java.util.Map.of(
                        "apiKey", "<override API key>",
                        "apiSecret", "<override API secret>",
                        "fromNumber", "<override from number>",
                        "url", "<alternate API url>"
                    )
                ))))
            .build())
        .build())
    .build();
SendMessageResponse response = client.send().message(params);

$response = $client->send->message(
  message: [
    'template' => 'nt_01kx4h2jdafq8bk9aftxak4b40',
    'to' => [
      'phone_number' => '+12345678901',
    ],
    'providers' => [
      'vonage' => [
        'override' => [
          'body' => [
            'text' => 'Override message text',
          ],
          'config' => [
            'apiKey' => '<override API key>',
            'apiSecret' => '<override API secret>',
            'fromNumber' => '<override from number>',
            'url' => '<alternate API url>',
          ],
        ],
      ],
    ],
  ],
);

SendMessageParams parameters = new()
{
    Message = new()
    {
        To = new UserRecipient { PhoneNumber = "+12345678901" },
        Template = "nt_01kx4h2jdafq8bk9aftxak4b40",
        Providers = new Dictionary<string, MessageProvidersType>()
        {
            {
                "vonage",
                new()
                {
                    Override = JsonSerializer.Deserialize<Dictionary<string, JsonElement>>(
                        """
                        {
                          "body": {
                            "text": "Override message text"
                          },
                          "config": {
                            "apiKey": "<override API key>",
                            "apiSecret": "<override API secret>",
                            "fromNumber": "<override from number>",
                            "url": "<alternate API url>"
                          }
                        }
                        """
                    ),
                }
            },
        },
    },
};

var response = await client.Send.Message(parameters);

courier send message \
  --api-key "$COURIER_API_KEY" \
  --message.to '{"phone_number": "+12345678901"}' \
  --message.template nt_01kx4h2jdafq8bk9aftxak4b40 \
  --message.providers '{"vonage": {"override": {"body": {"text": "Override message text"}, "config": {"apiKey": "<override API key>", "apiSecret": "<override API secret>", "fromNumber": "<override from number>", "url": "<alternate API url>"}}}}'

With Courier MCP, send my template to +12345678901 through Vonage from a different number.

Overrides are deep-merged into the request. Fields you set replace their counterparts, and fields you leave out are still sent. The full field list is in the Vonage SMS API docs.

Provider details

vonage

Courier recommends routing to the channel. Naming this key in routing.channels instead is supported, and sends through just this provider.

Send to a specific provider

When that is worth doing, and what you give up: failover, channel priority, and providers you add later.

Get started

Available integrations

Send SMS with Vonage through Courier

Prerequisites

Setup

Overrides

Provider details

Send to a specific provider

​Prerequisites

​Setup

​Overrides

​Provider details

Send to a specific provider

Prerequisites

Setup

Overrides

Provider details