Allows you to send a single message to one or more recipients or groups (as defined in your phone book).

Note on HTTP connections: please limit yourself to one concurrent connection, i.e., in your code, send with only one thread/process. If you feel that you have latency problems (if your computer is far away from our server in network terms), you could consider using HTTP KeepAlive.

Example (to two UK recipients, text Hi Mom & Dad - note URL-encoding):
http://bulksms.com.es:5567/eapi/submission/send_sms/2/2.0?username=john&password=
abcd1234&message=Hi+Mom+%26+Dad&msisdn=44123123456,44123123457

This example is so simple that it can be pasted into a browser's location bar. However, please do not use HTTP GET in production - use only POST. To ensure that you are using POST correctly, please use the Code Samples as a basis.

(Unable to connect? Experiencing connection timeouts? See the FAQ for port 80 access.)

Required parameters

(Parameter values should in encoded in ISO-8859-1)

• username
• password
• message: max 160 chars for text, max 280 chars for 8bit
• and one of:
  • msisdn (cell phone number): single recipient, or comma-separated list of recipients or
  • dest_group_id: comma-separated list of numeric group ids (we recommend a maximum of 5000 recipients across all groups to minimise timeouts)

Optional parameters

• sender: sender id / origin address (if alphanumeric, max 11 characters). This facility becomes available after credits have been purchased for the first time. To request a sender id, log into your account, go to User Account and click Change Sender ID. Alphanumeric sender id is a route-specific feature.
• msg_class: currently 0 (flash SMS) or 2 (normal SMS), default 2
• dca: Data Coding Alphabet: 7bit,8bit or 16bit, default 7bit (normal text message). For 8bit (ringtones,logos) or 16bit (Unicode), a message containing only hexadecimal octets, to a maximum of 140 octets (where an octet is e.g. ff), must be submitted (the UDHI is always set for 8-bit messages). 16-bit is a route-specific feature.
• want_report: 0 or 1, default 1
• routing_group: (previously known as cost_route, which still works to be backwards compatible) - possible values are 1,2,3 (it is possible but unlikely that these values could change - if they do, you should be contacted first). The current default is 2, but you would be wise to not depend on this remaining so. Routing groups group delivery routes by cost or quality.
• source_id: an alphanumeric (plus other common characters) id, for your own accounting purposes (e.g. useful if you have subaccounts that you send messages on behalf of, or even if you have your own unique id that you want to associate with the message). Max 20 characters. Reply messages that are pushed to you will include this parameter, based on the original message that they are in reply to.
• repliable: 1 to enable, 0 to disable, default is not set, which means that your User Profile's default repliable setting will prevail. Also see discussion on repliability below.
• strip_dup_recipients: set to 1 to enable, default is 0. Normally we return an error if your list of recipients is not unique. This setting causes the duplicates to rather be stripped and the messages be sent. Not recommended: you should rather validate your data properly.
• stop_dup_id: see section on eliminating duplicates below.
• send_time: scheduled send time (see section on scheduling below), in format yyyy-mm-dd hh:mm:ss, relative to the time zone specified for your account.
• send_time_unixtime: scheduled send time in integer format. This is an alternative to send_time, and represents the number of seconds since 1 Jan 1970 UTC (GMT+0), also known as unixtime.
• send_time_seconds: a flawed version of send_time_unixtime, provided only for backwards compatibility to clients already using it.
• scheduling_description: if using scheduling, you could provide a description of the scheduled job here to later help identify it.
• test_always_succeed: for testing purposes - if set to 1, does basic validation (username, password, etc) of your submission, but stops short of actually submitting the messages, and returns a successful status code as if it had submitted them successfully.
• test_always_fail: as for test_always_succeed, but after basic validation, always returns a failure code.
• allow_concat_text_sms: enable sending of messages longer than 160 characters (see Concatenation of long messages below). This is a route-specific feature. Set to 1 to enable, default is 0.
• concat_text_sms_max_parts: maximum number of message parts to allow when concatenating (default: 2).
• replace_msg_id: valid range: 1 to 7. Can be used to overwrite a previous message on the handset. See Overwriting messages on the handset below.
• protocol_id: See Protocol ID below.

Returns:

status_code|status_description|batch_id (where batch_id is optional, depending on the error)

Possible values for status_code are:

• 0: In progress (a normal message submission, with no error encountered so far).
• 1: Scheduled (see Scheduling below).
• 22: Internal fatal error
• 23: Authentication failure
• 24: Data validation failed
• 25: You do not have sufficient credits
• 26: Upstream credits not available
• 27: You have exceeded your daily quota
• 28: Upstream quota exceeded
• 40: Temporarily unavailable

You should never depend on the value of status_description - only depend on status_code, which is a constant. However, status_description can contain useful information about the nature of failures when you are developing your initial application. batch_id is guaranteed to be a positive integer > 0, if present.

Note: you should attempt to resend if you receive status code 40. You could also do so if you receive 26 or 28, which might have been resolved after several resend attempts. All other errors should be considered fatal.

Any HTTP status code other than 200 should be considered transient, i.e. you should attempt to resend after some interval.

URL

The current url is:
URL: http://bulksms.com.es:5567/eapi/submission/send_sms/2/2.0

(please also read the notes on versioning)

Repliability

Repliability is a feature whereby the originating address (sender id) of a message is set to a number at which we will collect replies on your behalf, and make them available to you. The feature of repliability will not necessarily be possible on your account or for your destination(s). Also be aware that we may not have reply numbers available for your specific country, which means that persons who reply may be exposed to higher costs than those of sending SMSs in their own country, and poorer delivery speed may also result. The repliable parameter is incompatible with the sender parameter. Additionally, this parameter will override any default sender id which you may have set up on your account.

Scheduling

Scheduling allows you to specify that a message be sent at a future date. Credits will be deducted immediately from your account, and once submitted, such a message cannot be cancelled.

If you specify a date/time in the past, your message will be sent immediately, and a status code of 0 will be returned. If you correctly specify a future date for sending, you will receive a status code of 1. Thereafter, you will not be able to request the status of a scheduled message until after it has actually been sent. The date that you supply must be in the time zone that your account is configured for.

If the destination is a group, the group members will be determined at the time that you submit the message, and not at the time the message is scheduled to be sent.

Please be sure to check our Terms and Conditions for any special conditions that may apply to scheduled messaging, e.g. adjustments that may need to be made for significant price changes where messages are scheduled far into the future.

Eliminating duplicates

Consider the case where you submit a message, but experience a network timeout (or your application crashes). Your application cannot know if we received and processed the message or not, and you are forced to resubmit it, possibly generating duplicates. If the message was to many recipients, this can be serious.

By submitting a unique id of your own along with every message that you submit, you can safeguard against this. The optional parameter stop_dup_id takes an integer as an argument, in the range 1 to 2147483647. If you submit a message with a stop_dup_id that you have recently (within the past few hours) used in another submission, then that submission will not be processed, and you will receive the response to the original submission, e.g.:
0|IN_PROGRESS|30430
(where 30430 is the batch_id that was generated by the original submission)

In other words, the process is entirely transparent to you, and you will never know whether your submission was processed during the first or the second attempt. Failure statuses are not recorded, so resubmitting a message which failed on its first submission will never result in you receiving a cached result.

stop_dup_id's are shared across send_sms and send_batch, so be sure not use the same id when using both API calls.

Concatenation of long messages

If you submit a message longer than 160 characters and have also specified the allow_concat_text_sms flag, if will automatically be split up into parts (of typically 153 characters each, but this figure could be lower to certain networks) and concatenated. These messages will be reconstructed by the recipient mobile, and appear to be a single message. All GSM handsets (except perhaps the very oldest) should support concatenation - it is not a vendor-specific feature, but is specified in GSM standards.

Use the concat_text_sms_max_parts parameter as a safeguard: it is possible that you calculated the length of the SMS differently to how we have, or even that we can't use all 153 characters to a given exceptional network. If our splitting process produces more message parts than this flag specifies, an error will be returned to you.

Concatenation is a route-specific feature. It may not work on most economy routes, and may not work on all premium routes either. It will definitely not work for American networks at present. Currently, concatenation is not supported for Unicode messages. Please test before assuming that concatenation works, for all your target networks.

Overwriting messages on the handset

The optional parameter replace_msg_id (valid range: 1 to 7) can be used to overwrite a previous message on the handset, provided that the previous message was sent with the same replace_msg_id and sender (origin address). This can be useful if you send frequent, related updates to a handset on a single issue, and only want the latest status to appear to the recipient. It also prevents filling up the recipient's Inbox. Use different replace_msg_ids to group related, overwritable issues together.

This feature may not work on all networks and/or routes (and in some cases, may even impede delivery). Also, choosing repliable will typically defeat this mechanism, because sender IDs may differ across messages, so you would typically only use this feature if you have been allocated your own, dedicated sender ID.

Protocol ID

For advanced used: the optional parameter protocol_id corresponds to the GSM PDU field TP-PID, and takes a decimal (not hexadecimal) argument. The most common use of the field is for specifying message replacement on the handset (and if that is all you need to do, you can use the shortcut method Overwriting messages on the handset above; note also the warnings in that section). For further uses, see the GSM 03.40 specification.

Previous versions

Documentation for older versions of this API can be found here

Route-specific features

Some features depend on how messages are routed, which again depends on certain pricing options which may have been applied to your account. Please contact us to find if such a feature is available to you, if unsure.

Upgrading notes

If upgrading from v1.x to v2.x, note that the nodup option has been deprecated and will return an error if specified. Also, the batch_id returned by 2.x onwards differs from the message_id returned by previous versions. The change should be transparent to you as long as you make sure that you:

• Use the new parameter batch_id instead of msg_id, if you have status reports pushed to you via HTTP.
• Also switch to version 2.0 of get_report, if you use the get_report API call.

---

ChangeLog

26-May-2009 Added comment specifying ISO-8859-1 encoding of parameter values. 11-Dec-2008 Added replace_msg_id and protocol_id. 23-May-2008 want_default default changed from 0 to 1. 15-Jun-2007 Added comment about URL encoding parameters. 06-Jun-2007 Documented SSL access where applicable. 13-Sep-2006 Documented port 80 access. 10-Oct-2005 Added comments about route-specific features. 29-Sep-2005 Added concatenation. 2-Mar-2005 Added sendtime_unixtime. 19-Oct-2004 stop_dup_id: no longer caching failed statuses, which was counter-intuitive - only successful statuses are cached. This new behaviour should however be backwards compatible. 13-Aug-2004 Version 2.0. Changed content type to text/plain. Now returning batch ids instead of message ids, for compatibility with send_batch. Removed deprecated nodup option. 5-Aug-2004 Added stop_dup_id. 28-Jul-2004 Added scheduling. 23-Jul-2004 Added source_id to existing v1.2; removed unused msg_id parameter. 18-Jun-2004 Added strip_dup_recipients to existing v1.2 25-Mar-2004 send_sms: renamed cost_route parameter to routing_group, with cost_route now an alias to routing_group. 9-Feb-2004 Added support for Greek and extended GSM characters. 30-Jan-2004 quote_sms version 1.1 published (note: several changes in URL). Added costing for messages to groups (dest_group_id). 22-Jan-2004 send_sms version 1.2 published. Added sending to groups (dest_group_id). 15-Jan-2004 added repliability options to existing version 1.1 of send_sms. 27-Aug-2003 added new cost_route options new optional param: nodup new faster url