Sending vCard messages using HTTP

Overview

OpenMarket now offers a RESTful and feature-rich Global SMS API. Compared to the existing MX Telecom APIs, the Global SMS API provides:

  • Automated originator selection, which selects the correct short code or VMN for any country or territory
  • Our highest level SLA and increased messaging capacity
  • Better security through Basic authentication
  • A test environment for new and migrating customers

as well as a host of other benefits. While we will continue to support our existing SMS APIs, we believe that our Global SMS API offers some exciting features and benefits that you'll want to take advantage of, and future feature development will be focused on the Global SMS API. For more information, see the Release Note on our Docs and Resources website.

Note that currently the Global SMS API does not support Premium Rate messaging. Existing Premium Rate customers should continue to use the MX Telecom APIs.

This page describes how to send a vCard message through the SMS Gateway. For information about integrating with the SMS Gateway, see either Sending a Single SMS or Broadcasting an SMS.

Sending a vCard

Single-recipient end points:

     http://sms.openmarket.com/sms/v1/send
     https://sms.openmarket.com/sms/v1/send

Broadcast end points: (HTTP POST only)

     http://sms.openmarket.com/sms/v1/bulksend
     https://sms.openmarket.com/sms/v1/bulksend

Example single-recipient request:

http://sms.openmarket.com/sms/v1/send?user=MyBulkAccount&pass=MyP4S5w0rD&smsto=447700900750&smsfrom=58870&vcard_data=BEGIN%3AVCARD%0D%0AVERSION%3A2.1%0D%0AFN%3AJohn+Smith%0D%0ATEL%3BWORK%3BVOICE%3A442071231234%0D%0ATEL%3BMOBILE%3BVOICE%3A447700900999%0D%0ATEL%3BHOME%3BFAX%3A442071231235%0D%0AEND%3AVCARD

This send a vCard for John Smith to the number 447700900750. Each line in the vCard must have a carriage return and line feed character (different mobile phones require either one of these characters). The URL encoding for these is %0D%0A.

The example vCard, before being URL encoded, has the following format and content:

BEGIN:VCARD
VERSION:2.1
FN:John Smith
TEL;WORK;VOICE:442071231234
TEL;MOBILE;VOICE:447700900999
TEL;HOME;FAX:442071231235
END:VCARD  

Mandatory parameters:

ParameterDescription
user The SMS Gateway account you are sending the message through.
pass The password for the SMS Gateway account.
smsto The MSISDN of the message recipient in international format (e.g. 447700900750). No leading "+" is required.
If you are sending a broadcast SMS request, separate each MSISDN with a line break (e.g. smsto=447700900750%0A447700900765%0A447700900999).
smsfrom Either a phone number (up to 16 digits) or an alphanumeric string encoded in the Modified Latin-9 character set (up to 11 characters). This parameter is mandatory for bulk services in all regions accept the US.
Regulatory requirements means that you cannot change the originator for Premium Rate SMS messages in any region. In these instances, the originator is always your service's Short Code. If you do set the originator, the SMS Gateway will ignore the value.
vcard_dataThe vCard you are sending.

Optional parameters specific to this request type:

There are no optional parameters specific to sending a vCard message request.

Optional parameters you can use for any request type:

  • submitid: used to send broadcast SMS messages
  • report: sets the delivery reports you want for the message
  • response: (for single-recipient requests only) changes the format of the HTTP response from the SMS Gateway
  • note, subaccount: optional reporting notes that you can add to the request
  • vp, billingsingleshot: alters the validity period and billing for the SMS message