Sending MMS via HTTP

Introduction

The MMS API is a HTTP endpoint used to send MMS messages.

Authorization

Please use your API Key's HTTP Token for authorization.

Endpoint

POST /api/v1/mms HTTP/1.1
Host: mms.tychron.online

Request Headers

Name	Default	Description	Example
Accept	application/json	Only JSON is currently supported for sending MMS via HTTP.	`Accept: application/json,/`
Authorization *	Authorization: Bearer KEY	Please use your API Key's HTTP Token for authorization.	`Authorization: Bearer Rb2VRMSsm0VxHOIcniw6hCJhUqRExQk2`
Content-Type		This header denotes the data type of a request body.	`Content-Type: application/json`

Response Codes

Code	Description	Solutions
200 OK	The request was successful and should contain the requested data.
400 Bad Request	The payload body of the request is malformed or the request contains invalid parameters.	Check your JSON payload for invalid or missing parameters, or run it through a JSON linter.
401 Unauthorized	The request may be deemed unauthorized due to a number of factors. The Authorization header is not set. The provided API HTTP token is invalid, expired, or not active. The requesting account may be unauthorized from making requests.	This error typically results from using an incorrect API token in requests. Check your API token for typos. If the error persists, please contact support. ([email protected])
403 Forbidden	The user is not permitted to make the specified request(s). In this instance, the user is likely not authorized to use the SMS API.	This error typically results from using an incorrect API token in requests. Check your API token for typos. Please contact support for additional details.([email protected])
415 Unsupported Media Type	The content-type used to make the request is not supported. At this time, only JSON is supported.	Convert the request to JSON. `Content-Type: application/json`
422 Unprocessable Entity	The parameters of the request body failed validation or contain invalid values.	The response body will contain specific details for the request failure. Correct the request parameters based on these details.
500 Internal Server Error	The request has not been fulfilled due to a server error.	Please report this error and contact support for further assistance. ([email protected])

Response Headers

Name	Description	Example
Content-Type	At this time, only application/json is supported and will be returned.	`Content-Type: application/json`
X-Request-ID	An ID used to identify the HTTP request.	`X-Request-ID: uYmqci22QoeTA8Zj`

Request Format

POST /mms HTTP/1.1
Host: mms.tychron.online
Accept: application/json
Authorization: Bearer YOUR_API_KEY_HERE
Content-Type: application/json

{
  "id": "my_message_id",
  "transaction_id": "[email protected]",
  "type": "mms_forward_request",
  "from": "+12003004000",
  "to": ["+12003004001"],
  "request_delivery_report": true,
  "request_read_reply_report": false,
  "parts": [
    {
      "id": "text-part",
      "body": "This is text"
    },
    {
      "id": "image-uri-part",
      "uri": "https://example.com/image.png"
    },
    {
      "id": "embedded-content-part",
      "transfer_encoding": "base64",
      "body": "BASE64DIGEST"
    }
  ]
}

Request Parameters

Parameters marked with * are mandatory in all requests.

Parameter	Type	Description	Example
Root
id	String	The ID used to identify the message.	"message1id"
type *	String	Used to specify whether the message is an MMS message. The parameter for sending MMS messages is"mms_forward_request"	"mms_forward_request"
from *	String	The sender number, should be formatted in E.164 format for non-shortcode numbers, e.g. (+12003004000) (65543)	"+12003004001"
to *	Array<String>	A list of recipient numbers each should be formatted in E.164 format.	[ "+12003004000","64573" ]
parts *	Array<Part>	An array containing the ids for each part (each attachment) in a multipart message. This parameter may be empty if the message is not a multipart message.
transaction_id	String	An ID identifying the request transaction (this ID will be returned with the response).	"message1id"
subject	String	A string to use for the message's subject.	"Test Subject"
request_delivery_ report	Boolean	Used to specify if a delivery report is required.	false
rrequest_read_ reply_report	Boolean	Used to specify if a reply report is required.	false
Part
id	String	An ID used to identify one part (one attachment) of a multipart message.	"part1id"
content_type	String	A MIME type (media type) that identifies the content of the message.	"text/plain"
transfer_encoding	String	An encoding that is applied to the message body when transferring via JSON. The encoding can be either base64 or identity.	"base64"
body * (required if no uri is provided)	String	The body of the part. If the "transfer_encoding"parameter is used, the part body should be encoded.	"Hello, World"
uri * (required if no body is provided)	String	A URL to a specified resource. The content type will be determined by the file's extension. There is a 2mb limit on any files (this includes the HTTP overhead). As a rule of thumb, try to keep file sizes below 1mb, as most carriers will reject messages containing content larger than 1mb. Please note that in some cases, carriers limit files sizes to as low as 500kb. If you require further details regarding carrier restrictions on file sizes, please contact ([email protected]).	"https://example.com/image.png"

Response Format

HTTP/1.1 200 OK
Content-Type: application/json
X-Request-ID: uYmqci22QoeTA8Zj

{
  "records": [
    {
      "id": "01EYVMW463NZSY6E26NMNN7H2N",
      "type": "mms_forward_request",
      "reference_id": "my_message_id",
      "inserted_at": "2021-02-18T22:39:43Z",
      "from": "12003004000",
      "to": ["12003004001"],
      "request_delivery_report": true,
      "request_read_reply_report": true
    }
  ],
  "errors": [
  ]
}

Please note the above example is for demonstrative purposes only.

Response Parameters

Parameters marked with * are always present in all requests

Parameter	Type	Description	Example
Root
records	Array<Response>	An array of responses
Response
id *	String	The ID supplied by the system to identify the message.	"01EYVMVWJQ9F3VYAJ833W9GZJ9"
reference_id	String	The ID originally supplied in the requests	"my_message_id"
from *	String	The sender number	"12003004000"
to *	Array<String>	The recipient number, which is identical to the key.	"12003004001"
type *	String	The created message type which may be an sms or mms message based on account settings.	"sms"
request_delivery_report *	Boolean	Denotes under what conditions a delivery report be sent back for the message.	true
request_read_reply_report *	Boolean	Denotes under what conditions a read-reply report be sent back for the message.	true
inserted_at	updated_at	Denotes when the message's status was last modified.	"2020-04-18T11:30:00Z"

References

E.164

The E.164 format is the international telephone numbering plan that gives each device on the Public Switched Telephone Network (PSTN) a globally unique number.

The E.164 format consists of a 7 to 15 digit number prepended with a "+" character.

Examples: +12003004000, +332828373552

Encodings

identity: The message body is sent exactly as is.
base64: The message body is encoded using base64.