Umes
Documentation Powered by Umes.io

Umes API (v1.0.0)

Download OpenAPI specification:Download

E-mail: support@umes.io

Introduction

Api endpoint

https://api.umes.io

Umes REST API allows you to send and receive messages through multiple channels.

Authentication

Authentication is done with API KEY that you can find in your personal dashboard under section Developers->Keys

Add the header Authorization: YOUR_API_KEY to each REST request for authentication.

N.b. There are some APIs like GetMessage where you can add API_TOKEN in query params because sometimes is more simpler to have one single GET request without headers, but if possible, please use the authorization header.

Messages [Outbound]

Outbound messages are messages sent OUT with sms, telegram or fax channel.

Get message

query Parameters
id
required
string

Message id

Responses

Request samples 

curl --request GET 'https://api.umes.io/message?id=ID_HERE' \
--header 'authorization: API_TOKEN_HERE'

Response samples

Content type
application/json
{
  • "id": "0bf389be-04bb-4dcb-b67d-ca04570b26fx",
  • "type": "sms",
  • "to": "+39399332233xxx",
  • "from": "umes",
  • "body": "hello",
  • "status": "DELIVERED",
  • "createdon": 1610121088573321000,
  • "sms": {
    },
  • "telegram": { },
  • "fax": { }
}

Send message over query parameters

Authorizations:
api_key
query Parameters
type
required
string
Enum: "sms" "telegram" "umes"

Provider

msg
required
string

Message text

recipient
required
string

Message recipient

alias
required
string [ 3 .. 14 ] characters

Sender ( alphanumeric )

callback
string

Callback url

apitoken
string

you can put apitoken in query params istead of putting in headers

Responses

Request samples 

curl --location --request GET 'https://api.umes.io/sendmessage?type=sms&msg=TEXT_HERE&recipient=RECIPIENT_HERE&alias=ALIAS_HERE&callback=OPTIONAL_CALLBACK_HERE&apitoken=APITOKEN_HERE'

Response samples

Content type
application/json
{
  • "uuid": "0bf389be-04bb-4dcb-b67d-ca04570b26fd",
  • "to": "+39348********",
  • "sender": "Umes",
  • "text": "Hello",
  • "createdon": 1610121088573321000,
  • "type": "sms",
  • "userID": "youremail@email.com",
  • "state": "accepted",
  • "textLenght": 5,
  • "smsPartLength": 160,
  • "smsCount": 1,
  • "encoding": "GSM-7",
  • "country": "ITALY"
}

Send message

N.B. The first state of message is ACCEPTED

Authorizations:
api_key
Request Body schema: application/json
msg
required
string

Message text

recipient
required
string

Message recipient

from
required
string

Message sender

type
required
string
Enum: "sms" "telegram" "umes"
reference
string

Custom ID set by user

autodetectlang
boolean
Default: false

Auto detecte language

langcode
string
Enum: "ES" "PT" "TR"

Use shift tables for selected language

intermediatestatecallback
boolean
Default: false

Get callback for each state of message istead of final states ( like SENDING )

callback
string

Callback url ( HTTP POST will be made )

callbacakcontenttype
string
Enum: "json" "xml"

Callback content format

callbackextradata
string

Dati aggiuntivi ( arbitrari ) che verranno ritornati con la callback

Responses

Request samples

Content type
application/json
{
  • "msg": "string",
  • "recipient": "string",
  • "from": "string",
  • "type": "sms",
  • "reference": "string",
  • "autodetectlang": false,
  • "langcode": "ES",
  • "intermediatestatecallback": false,
  • "callback": "string",
  • "callbacakcontenttype": "json",
  • "callbackextradata": "string"
}

Response samples

Content type
application/json
{
  • "uuid": "0bf389be-04bb-4dcb-b67d-ca04570b26fd",
  • "to": "+39348********",
  • "sender": "Umes",
  • "text": "Hello",
  • "createdon": 1610121088573321000,
  • "type": "sms",
  • "userID": "youremail@email.com",
  • "state": "accepted",
  • "textLenght": 5,
  • "smsPartLength": 160,
  • "smsCount": 1,
  • "encoding": "GSM-7",
  • "country": "ITALY"
}

Messages [Inbound]

To enable inbound messages you have to request at dev@umes.io a Virtual Mobile Number (VMN).

Other then APIs you can than configure a callback URL ( one custom URL per (VMN).

Get received messages

The messages will be delivered only ONE TiME

query Parameters
apitoken
required
string

User api token

Responses

Request samples 

curl --request GET 'https://api.umes.io/inbound_sms?apitoken=API_TOKEN_HERE'

Response samples

Content type
application/json
[
  • {
    }
]

Alias

🇮🇹 Italian customers in order to use use a custom alphanumeric sender ( ALIAS ) needs to register it with our APIs.

Get alias

The messages will be delivered only ONE TiME

Authorizations:
api_key
query Parameters
id
required
string

Message id

Responses

Request samples 

curl --location --request GET 'https://api.umes.io/alias?id=ALIAS_ID_HERE' \
--header 'authorization: API_KEY_HERE'

Response samples

Content type
application/json
{
  • "id": "e2f3fd3b-89a2-4f5c-8c8a-f83cs937ab11",
  • "status": "REQUESTED",
  • "userID": "string",
  • "requestedAt": 1649261507,
  • "alias": "Umes",
  • "companyName": "Umes Inc.",
  • "companyCountryCode": "IT",
  • "fiscalCode": "883283823232",
  • "vatNumber": "883283823232",
  • "pec": "tomtest@pec.com",
  • "contact": {
    }
}

Get all

The messages will be delivered only ONE TiME

Authorizations:
api_key

Responses

Request samples 

curl --location --request GET 'https://api.umes.io/alias/all' \
--header 'authorization: API_KEY_HERE'

Response samples

Content type
application/json
[
  • {
    }
]

Register alias

Authorizations:
api_key
Request Body schema: application/json
alias
string [ 3 .. 11 ] characters

alphanumeric sender

companyName
string

company name

companyCountryCode
string

ISO country code

fiscalCode
string
vatNumber
string
pec
string

pec mail

object

Contact object

Responses

Request samples

Content type
application/json
{
  • "alias": "Umes",
  • "companyName": "Umes Inc.",
  • "companyCountryCode": "IT",
  • "fiscalCode": "883283823232",
  • "vatNumber": "883283823232",
  • "pec": "tomtest@pec.com",
  • "contact": {
    }
}

Response samples

Content type
application/json
{
  • "id": "e2f3fd3b-89a2-4f5c-8c8a-f83cs937ab11",
  • "status": "REQUESTED",
  • "userID": "string",
  • "requestedAt": 1649261507,
  • "alias": "Umes",
  • "companyName": "Umes Inc.",
  • "companyCountryCode": "IT",
  • "fiscalCode": "883283823232",
  • "vatNumber": "883283823232",
  • "pec": "tomtest@pec.com",
  • "contact": {
    }
}