URL shortening

Shortens a target URL into a short link you can then use in a message text or in the BulkGate Portal.

API URL

The URL used to send the HTTP requests:

https://portal.bulkgate.com/api/1.0/shortener/shorten

Note

If the request does not reach its destination, repeat it on the backup server backup1.bulkgate.com.

Supported HTTP methods

POST - application/json

POST /api/1.0/shortener/shorten HTTP/1.1 Host: portal.bulkgate.com Content-Type: application/json

Note

The API has a quota of 20 requests per minute.

Parameters table

PARAMETER NAME	VALUE	MANDATORY	DEFAULT VALUE
application_id	Application ID	Yes	-
application_token	Application authentication token	Yes	-
target_url	Url to be shortened	Yes	-
url_type	Domain of the short link, see Supported domains	No	`ur7.wf`

Supported domains

The url_type values are instance configuration and do change — the current list for your account is returned by the `domains` endpoint. At the time of writing:

DOMAIN	TARGET ADDRESS RESTRICTION
`ur7.wf`	No restriction. Default value.
`ms6.fr`	No restriction.
`ur7.yt`	Whitelisted target domains only.
`ur7.tf`	Whitelisted target domains only.
`ms6.wf`	Whitelisted target domains only.
`ms6.tf`	Whitelisted target domains only.
`track-message.com`	Whitelisted target domains only.

For the restricted domains the target address must be on your account's whitelist, otherwise the request fails with domain_is_not_white_listed. A handful of public services (Google, YouTube, Facebook, GitHub and others) are always whitelisted.

Request example

POST /api/1.0/shortener/shorten HTTP/1.1 Host: portal.bulkgate.com Content-Type: application/json { "application_id": 451, "application_token": "NKN02TWE6NfBkfl-your-secret-token-Wf05GaqLIWLW4aBj", "target_url": "www.bulkgate.com", "url_type": "ur7.wf" }

Response

In case of success:

{ "data": { "short_url": "http://ur7.wf/W", "target_url": "http://www.bulkgate.com/", "final_url": "http://www.bulkgate.com", "title": "SMS & other channels for business communication | BulkGate", "expiration": "2026-10-10T09:00:00+02:00" } }

Links created through the API are valid for 30 days — expiration carries the expiry date in ISO 8601.

The three URL fields are not the same thing:

FIELD	VALUE
`short_url`	The shortened link itself, built from `url_type` and the generated key
`target_url`	The address as it was stored — the scheme is added when missing and the URL is normalised, so `www.bulkgate.com` becomes `http://www.bulkgate.com/`
`final_url`	The address you sent, only with the scheme added. Redirects are not followed, so this is not the page the visitor ends up on
`title`	Title read from the target page

In case of error:

{ "type": "url_is_not_valid", "code": 400, "error": "Url is not valid", "detail": null }

{ "type": "the_per_minute_quota_has_been_exceeded", "code": 400, "error": "The per minute quota has been exceeded", "detail": null }

Where:

type and error (description of the error) can be found in the error types table
code is the HTTP error code
detail is additional information about the error

Shortener API error types

Besides the general types, the Shortener API returns its own:

TYPE	WHEN IT HAPPENS
`url_is_not_valid`	`target_url` could not be parsed.
`url_type_is_incorrect`	`url_type` is not in the account's domain list.
`domain_is_not_white_listed`	The target domain is not whitelisted (for restricted domains).
`url_is_not_allowed`	The target address points to a local/internal address.
`url_can_not_be_redirected_out_of_target_domain`	The target address redirects outside its own domain.
`url_can_not_be_created`	The link could not be created.
`the_per_minute_quota_has_been_exceeded`	The quota of 20 requests per minute is used up.

Was this page helpful?

Ask AI Copied