NAV Navbar
cURL
  • Overview
  • Getting Started
  • Filtering Resources
  • Payment and billing
  • Send SMS API
  • Concatenation and Encoding
  • Limitations
  • SMS Statistics
  • Export SMS Statistics
  • Error Codes
  • Overview

    Mailjet’s SMS API allows you to send text messages to users around the globe through a simple RESTful API. The main functionalities of the SMS API inlcude:

    This documentation will provide instructions on how to quickly integrate Mailjet's SMS API into various solutions. In order to interact with our API, any HTTP client in any programming language can be used.

    Getting Started

    You want to start using Mailjet's SMS service and are not sure where to begin? We've got your back - please follow these essential steps to get started.

    Add Money to Mailjet's SMS Wallet

    Having credits in your SMS Wallet is a requirement for sending SMS. If you do not yet have funds in your wallet, you can deposit directly in the Mailjet app.

    Accepted currencies are USD, EUR and GBP and the minimum deposit amount is 1 unit in the respective currency.

    Keep in mind that due to necessary verification procedures there is a 48-hour waiting period before your wallet is activated. See Payments & Billing for additional information.

    Retrieve Your Access Token

    When using the Mailjet SMS API, the authentication of your requests is done using Bearer Tokens. Bearer Tokens are a compact, URL-safe means of representing claims to be transferred between two parties.

    To generate a new token, please go Mailjet's SMS Dashboard and click on 'Generate a token'.

    Keep in mind that for security reasons a token is only displayed once. Make sure to save the token value locally before closing the modal window.

    Any additional information can be found in our detailed guide.

    Send Your First SMS

    Your balance has just been credited and your account activated - now let's send your first SMS.

    The endpoint to be called is https://api.mailjet.com/v4/sms-send.

    You must be authenticated with a Bearer Token. That's a different method from the one used for Emails - your access token must be included in the Authorization header of your request.

    cURL Example:

    curl -X POST \
      https://api.mailjet.com/v4/sms-send \
      -H "Authorization: Bearer $MJ_TOKEN" \
      -H 'content-type: application/json' \
      -d '{
      "From": "InfoSMS",
      "To": "+33600000000",
      "Text": "Hello World!"
    }'
    

    Fill your sending information in the payload. Three properties are required:

    Filtering Resources

    https://api.mailjet.com/v4/endpoint?filter1=this&filter2=that&filter3=it
    

    The Mailjet API provides a set of general filters that can be applied to a GET request for each resource. In addition to these general filters, each API resource has its own filters that can be used when performing the GET. You can find these filters in their respective resource description.

    To use a filter in a GET, you can amend the resource URL with a standard query string (?filter1=this&filter2=that&filter3=it).

    Mailjet API supports filter combination following these rules:

    The Limit Filter

    # View : List of 100 SMS messages
    curl -s \
        -X GET \
        -H "Authorization: Bearer $MJ_TOKEN" \
        https://api.mailjet.com/v4/sms?Limit=100 
    

    You can limit the number of results by applying the Limit filter. The default value is 10 and the maximum value is 1000. Limit=0 delivers the maximum amount of results - 1000.

    The Offset Filter

    # View : List of SMS messages with Offset, starting with the 25000th contact
    curl -s \
        -X GET \
        -H "Authorization: Bearer $MJ_TOKEN" \
        https://api.mailjet.com/v4/sms?Offset=25000 
    

    You can use the Offset filter to retrieve a list starting from a certain offset.

    # View : List of SMS with Limit and Offset, retrieves a list of 150 SMS starting with the 25000th contact
    curl -s \
        -X GET \
        -H "Authorization: Bearer $MJ_TOKEN" \
        https://api.mailjet.com/v4/sms?Limit=150\&Offset=25000 
    

    The Offset filter can be combined with the Limit filter.

    Date Range Filters

    # View : List of contacts sent between March 1st 2018 00:00 UTC and March 10th 2018 00:00 UTC
    curl -s \
        -X GET \
        -H "Authorization: Bearer $MJ_TOKEN" \
        https://api.mailjet.com/v4/sms?FromTS=1519862400\&ToTS=1520640000 
    

    Use the FromTS and ToTS filters (Unix timestamp) to specify a time period, for which to retrieve the information you need.

    Payment and billing

    How to Fund Your SMS Wallet

    In order to properly use the Send SMS API to send messages, you need to add money to your SMS wallet first.

    To do that, please go to the SMS Subscription page. You can deposit in EUR, GBP or USD, with a minimum deposit amount of 1 unit.

    SMS Wallet Currency

    Please keep in mind that the deposit currency will determine your SMS wallet currency - e.g. if you make your deposit in EUR, the SMS wallet will also take EUR as its base currency.

    SMS Wallet Currency Change

    The Mailjet account currency (and subsequently, the one for your SMS wallet) can be changed by depositing into your SMS wallet, or paying for your Mailjet subscription plan, in a different currency.

    However, when the currency is changed, the funds already present in the wallet will not be converted into the new currency. Instead, the SMS service will be switched to a different wallet in the new currency. The amount in the original wallet will become inaccessible until such a time, when you switch to it with a new money transfer in the respective currency.

    Example:

    Waiting Period after Initial Deposit

    Upon your first deposit into your SMS wallet Mailjet needs to complete mandatory security checks, which take 48 hours, before you are able to send messages. Meanwhile the payment will be put on hold. Once the checks are complete and no issue with your account is detected, we will proceed with the payment and subsequent activation of your SMS wallet.

    Keep in mind that the 48-hour verification period will be in effect every time you deposit with a new credit card.

    SMS Billing

    Upon each SMS send request, your SMS wallet will be automatically billed. The cost depends on the pricing for the respective country, as well as the number of SMS parts the message consists of, indicated by the SMSCount property.

    Automatic Balance Check

    Before the SMS message is sent, your SMS wallet balance will be automatically checked to ensure that there are enough funds to cover the cost of sending the message. If there are insufficient funds, an error message will be returned.

    Return Transactions

    In cases where your SMS wallet is billed for sending the message, but the SMS could not be sent out (e.g. due to an issue with the processor), the transaction will be automatically reverted.

    Use of SMS API by Sub-accounts

    Since token generation is only available on a master account, currently it is not possible for sub-accounts to use the SMS API.

    Send SMS API

    Send Transactional SMS

    Mailjet allows you to send transactional SMS messages using our Send SMS API.

    The following API endpoint has been designed to provide this service: POST /sms-send.

    The input payload needs to include the following array of properties:

    Authentication

    In order to invoke a service protected by an access token, it is necessary to include the access token in the Authorization header. The Security proxy will then validate it.

    # Create : Send SMS Message to a selected recipient.
    curl -X POST \
     https://api.mailjet.com/v4/sms-send \
      -H "Authorization: Bearer $MJ_TOKEN" \
      -H 'Content-Type: application/json' \
      -d '{
        "Text": "Have a nice SMS flight with Mailjet !",
        "To": "+33600000000",
        "From": "MJPilot"
      }'
    

    In the code sample you can see a POST request with an Authorization header that includes the token value.

    API Response

    {
      "From": "MJPilot",
      "To": "+33600000000",
      "Text": "Have a nice SMS flight with Mailjet !",
      "MessageId": "2034075536371630429",
      "SmsCount": 1,
      "CreationTS": 1521626400,
      "SentTS": 1521626402,
      "Cost": {
        "Value": 0.0012,
        "Currency": "EUR"
      },
      "Status": {
        "Code": 2,
        "Name": "sent",
        "Description": "Message sent"
      }
    }
    

    The Send SMS API will send a response, which will include the Status of the message, as well as its MessageID, time of creation, SmsCount (how many SMS parts were needed to send the whole message) and Cost.

    Concatenation and Encoding

    When you send SMS with Mailjet, you should be aware of how many parts your message is being sent as, and what type of encoding is required to send your message.

    Overview

    Every SMS message has a limit for the characters it may contain for the chosen encoding. If you send a message that contains more than that limit, Mailjet will send a concatenated SMS.

    A concatenated SMS contains multiple (up to 5) SMS parts that are connected by segmentation information in the User Data Header (UDH).

    Segmentation information tells the handset the number of messages that make up the concatenated SMS, and the position of each SMS part in the concatenated SMS. The parts of a concatenated SMS arrive at the user's handset out of sequence. When the handset has received all SMS parts, it presents your message as a single text to your user.

    The maximum number of characters you can fit into an SMS part depends on the Encoding you are using.

    Number of SMS messages GSM7 UNICODE
    1 standard SMS message up to 160 characters up to 70 characters
    2 concatenated SMS messages up to 306 characters up to 134 characters
    3 concatenated SMS messages up to 459 characters up to 201 characters
    4 concatenated SMS messages up to 612 characters up to 268 characters
    5 concatenated SMS messages up to 765 characters up to 335 characters

    GSM7 Encoding

    Example for message encoded in GSM7:

    {
      "From":"WineShop",
      "To":"+33600000000",
      "Text":"Wine has been produced for thousands of years, with the earliest wines being drunk c. 6000 BC in Georgia. It had reached the Balkans by c. 4500 BC and was consumed and celebrated in ancient Greece and Rome."
    }
    

    GSM-7 is a character encoding standard which packs the most commonly used letters and symbols in many languages into 7 bits each for usage on GSM networks. As SMS messages are transmitted 140 8-bit octets at a time, GSM-7 encoded SMS messages can carry up to 160 characters.

    GSM-7 is the standard alphabet for SMS messages, written up in the standard GSM 03.38. It is always supported on GSM networks.

    The basic character set for GSM-7 can be found here.

    The Text property in the SMS sample message contains 206 characters, which means that it will be sent as 2 concatenated parts.

    UNICODE (UTF-16) Encoding

    Example for message encoded in UNICODE:

    {
      "From":"WineShop",
      "To":"+33600000000",
      "Text":"Hello world, Καλημέρα κόσμε, コンニチハ. Wine has been produced for thousands of years, with the earliest wines being drunk c. 6000 BC in Georgia. It had reached the Balkans by c. 4500 BC and was consumed and celebrated in ancient Greece and Rome."
    }
    

    UNICODE is a character encoding standard in which characters are represented by a fixed-length 16 bits (2 bytes). It is used as a fallback on many GSM networks when a message cannot be encoded using GSM-7, or when a language requires more than 128 characters to be rendered.

    UTF-16 is defined by the international Organization for Standardization (ISO) in ISO 10646.

    UTF-16 represents a possible maximum of 65,536 characters, or in hexadecimals from 0000h - FFFFh (2 bytes). The characters in UTF-16 are synchronized to the Basic Multilingual Plane in UNICODE.

    The sample message contains Greek & Japanese characters, so it needs to be encoded in UNICODE. It contains 242 characters, hence it will be sent as 4 concatenated SMS parts.

    Limitations

    When using Mailjet's SMS service you may encounter default restrictions of service. Please keep them in mind and feel free to contact us in case you have any questions.

    General API Limitations

    Deliverability Limitations

    SMS messages sent to countries that are not supported cannot be delivered successfully. Please visit our Pricing Page and use the pricing calculator for more information on supported countries and sending prices.

    We review the list of countries regularly and may allow SMS sending to new countries and regions in the future. You can contact our Support team to request the opening of a specific country.

    Country Specific Limitations

    Different jurisdictions may impose restrictions of their own. Depending on the jurisdiction, one or more of the following may apply:

    SMS Statistics

    Retrieve List of Messages

    # View : Retrieve a list of SMS messages sent during a specific time period
    curl -s -X GET \
    -H "Authorization: Bearer $MJ_TOKEN" \
    https://api.mailjet.com/v4/sms?FromTS=1033552800&ToTS=1033574400
    

    With GET on the /sms endpoint you are able to view details for a list of existing messages - Status, Cost, MessageID, sender and recipient, CreationTS and SentTS timestamps etc.

    A maximum of 21 items can be retrieved per call, but a default pagination is provided in order to ensure that you have access to the full data you need.

    API Response

    {
      "Data":[
        {
          "From": "MJPilot",
          "To":"+33600000000",
          "Status": {
            "Code": 2,
            "Name": "sent",
            "Description": "Message sent"
          },
          "MessageId":"744ecf8c-9fed-4ec9-acd0-9b326671f5df",
          "CreationTS": 1033552800,
          "SentTS": 1033552802,
          "SMSCount":1,
          "Cost": {
            "Value": 0.04,
            "Currency": "EUR"
          }
        },
        {
          "From": "MJPilot",
          "To":"+33600000000",
          "Status": {
            "Code": 2,
            "Name": "sent",
            "Description": "Message sent"
          },
          "MessageId":"fabed50c-8c84-4472-bd48-8cccc13ef829",
          "CreationTS": 1033552810,
          "SentTS": 1033552812,
          "SMSCount":2,
          "Cost": {
            "Value": 0.08,
            "Currency": "EUR"
          }
        }
      ],
    }
    

    Use FromTS and ToTS to specify a timeframe - if no timeframe is selected, Mailjet will automatically pull the stats for the last 3 months. Please note that messages will be ordered based on the CreationTS property, from the most recently created to the oldest one.

    Stats by Recipient

    # View : Retrieve a list of SMS messages sent to a specific recipient
    curl -s -X GET \
    -H "Authorization: Bearer $MJ_TOKEN" \
    https://api.mailjet.com/v4/sms?To=+33600000000
    

    API Response

    {
      "Data":[
        {
          "From": "MJPilot",
          "To":"+33600000000",
          "Status": {
            "Code": 2,
            "Name": "sent",
            "Description": "Message sent"
          },
          "MessageId":"744ecf8c-9fed-4ec9-acd0-9b326671f5df",
          "CreationTS": 1033552800,
          "SentTS": 1033552802,
          "SMSCount":1,
          "Cost": {
            "Value": 0.04,
            "Currency": "EUR"
          }
        },
        {
          "From": "MJPilot",
          "To":"+33600000000",
          "Status": {
            "Code": 2,
            "Name": "sent",
            "Description": "Message sent"
          },
          "MessageId":"d78b4d97-a001-4924-8184-804013f1b11a",
          "CreationTS": 1033552821,
          "SentTS": 1033552825,
          "SMSCount":3,
          "Cost": {
            "Value": 0.12,
            "Currency": "EUR"
          }
        }
      ],
    }
    

    If you want to view the stats for a specific recipient, simply use the To property with your request.

    Keep in mind that the complete phone number should be entered, as described in the Send SMS API section.

    Stats by Message Delivery Status

    # View : Retrieve a list of SMS messages that were successfully sent, or are being currently sent
    curl -s -X GET \
    -H "Authorization: Bearer $MJ_TOKEN" \
    https://api.mailjet.com/v4/sms?StatusCode=1,2
    

    API Response

    {
      "Data":[
        {
          "From": "MJPilot",
          "To":"+33600000000",
          "Status": {
            "Code": 2,
            "Name": "sent",
            "Description": "Message sent"
          },
          "MessageId":"744ecf8c-9fed-4ec9-acd0-9b326671f5df",
          "CreationTS": 1033552821,
          "SentTS": 1033552802,
          "SMSCount":1,
          "Cost": {
            "Value": 0.04,
            "Currency": "EUR"
          }
        },
        {
          "From": "MJPilot",
          "To":"+33600000000",
          "Status": {
            "Code": 1,
            "Name": "sent_pending",
            "Description": "Message is being sent"
          },
          "MessageId":"fabed50c-8c84-4472-bd48-8cccc13ef829",
          "CreationTS": 1033552832,
          "SentTS": "",
          "SMSCount":2,
          "Cost": {
            "Value": 0.08,
            "Currency": "EUR"
          }
        }
      ],
    }
    

    Use the StatusCode property with your request to see only messages with specific statuses - e.g. Rejected ones because of an invalid phone number.

    For more information on Status Codes and what they correspond to, please see the list of status codes.

    List of Status Codes

    Code Name Description
    0 unknown There is no record in Mailjet for the status code returned by the provider.
    1 sent_pending Message is being sent
    2 sent Message sent
    3 delivered Message delivered
    4 rejected_operator Message rejected by the operator
    5 rejected_undelivered Message declared as "undelivered" by the operator
    6 rejected_expired Message has been sent to the operator but expired
    7 rejected_incorrect_delivery Message has been sent to the operator but the delivery report is not correct
    8 rejected_network Message has been sent to the operator but encountered a network or setup issue
    9 rejected_dnd Message has been sent to the operator but recipient is subscribed to Do Not Disturb services
    10 rejected_from_blacklist Message rejected because sender is blacklisted
    11 rejected_to_blacklist Message rejected because recipient is blacklisted
    12 rejected_anti_flood Message has been rejected due to an anti-flooding mechanism
    13 rejected_system_error Message rejected due to an expected system error
    14 invalid_phone_number The phone number specified is invalid.
    15 rejected_insufficent_funds Message is rejected as you have not enough funds to send the message.
    16 rejected_daily_limit_reached Message is rejected as you have reached your maximum number of messages sent for today.

    Retrieve SMS Count

    # View : Retrieve the number of SMS messages that were processed within a specific timeframe
    curl -s -X GET \
    -H "Authorization: Bearer $MJ_TOKEN" \
    https://api.mailjet.com/v4/sms/count?FromTS=1033552800&ToTS=1033574400
    

    API Response

    {
      "Count": 31
    }
    

    Use GET on /sms/count to retrieve the number of messages already processed. You can filter the results by entering a period of time (with FromTS and ToTS) or a status you are interested in (with StatusCode).

    Export SMS Statistics

    Exporting SMS Statistics into a CSV file is an asynchronous process and consists of two separate requests:

    1. Ask for your document to be generated.
    2. Retrieve the link to download the CSV file, once it has been successfully created.

    CSV Generation

    # Create : Create a CSV export file with a list of SMS messages for a specific time period
    curl -s -X POST \
    -H "Authorization: Bearer $MJ_TOKEN" \
    https://api.mailjet.com/v4/sms/export \
    -H 'Content-Type: application/json' \
    -d '{"FromTS": 1033552800, "ToTS": 1033574400}'
    

    A POST on the /sms/export endpoint gives you the ability to request a CSV export file to be generated. With your request you are required to submit a specific timeframe using the FromTS and ToTS properties.

    When the request is accepted a process for the creation of the document will be queued. For each state of the creation there is a different status, when the state is changed that status will be updated. When the document is created it will be uploaded to our server.

    API Response

    {
      "ID":56654,
      "CreationTS":null,
      "ExpirationTS":null,
      "Status":{
        "Code": 1,
        "Name": "PENDING",
        "Description": "The request is accepted."
      },
      "URL":null,
      "FromTs":1033552800,
      "ToTs":1033574400
    }
    

    The response will include an Request ID under the ID property. Make sure to save it, as you need it to check the export status and see the URL to download the CSV file.

    Check Status / Retrieve Export URL

    # View : Check the status of an export request and retrieve the download URL, if ready
    curl -s -X GET \
    -H "Authorization: Bearer $MJ_TOKEN" \
    https://api.mailjet.com/v4/sms/export/$ID
    

    Use GET on /sms/export/{RequestID} to check the status of your export request, and to retrieve the download URL, once the export file is ready.

    API Response

    {
      "ID":56654,
      "CreationTS":1033674500,
      "ExpirationTS":1034236100,
      "Status": {
        "Code": 3,
        "Name": "COMPLETED",
        "Description": "The export completed without errors."
      },
      "URL": "https://api.mailjet.com/v3/data/rfh9o9fn92n9u29r3hjf2.csv",
      "FromTs":1033552800,
      "ToTs":1033574400
    }
    

    List of Export Status Codes

    Code Name Description
    1 PENDING The request is accepted.
    2 IN_PROGRESS The export is in progress.
    3 COMPLETED The export completed without errors.
    4 ERROR The export is in error state.

    Error Codes

    In this section we'll include detailed descriptions of the error codes you might encounter when using the different endpoints of the SMS API.

    Send SMS Error Codes

    Error Code Error Message Case Description Error Related To Status Code
    sms-0001 Insufficient funds. There are not enough funds in the AKID's SMS wallet, or no deposit has been made in this currency. 400
    sms-0002 Unsupported country code. The value does not start with any of the accepted country codes. To 400
    sms-0003 SMS per day limit reached. Daily SMS sending limit has been reached. 400
    sms-0004 No account. when no account or when account has not been set yet. 400
    mj-0002 Malformed JSON, please review the syntax and properties types. The API user has sent a JSON with an invalid syntax. 400
    mj-0003 Missing mandatory property. A mandatory property is missing or with null value. The functional specification defines mandatory properties. To, From or Text 400
    mj-0004 Type mismatch. Expected type "[property]". The value type for the respective property is incorrect. To, From or Text 400
    mj-0006 Characters limit exceeded for the property. Max allowed - [number]. The string contains more than the maximum allowed characters. To, From or Text 400
    mj-0011 Input payload must be less than [size]MB. The payload size is over the limit. 400
    mj-0015 Not authorised. The user did not provide valid authorization credentials. 401
    mj-0020 Characters limit below the minimum for the property. Min allowed - [number]. The string contains less than the minimum allowed characters. From or To 400
    mj-0021 You do not have access to this resource. The AKID does not have access to the resource. 403

    SMS Stats Error Codes

    For GET /sms:

    Error Code Error Message Case Description Error Related To Status Code
    mj-0004 Type mismatch. Expected type "[t]". The provided value type is unexpected. FromTS, ToTS, StatusCode, Offset or Limit 400
    mj-0005 Value "[value]" is invalid. Allowed values are: [allowedValues]. The provided value is not in the array of allowed values. StatusCode 400
    mj-0009 The datetime value "[date]" is not a valid RFC3339 datetime format. The timestamp value is not a valid RFC3339 format. FromTS or ToTS 400
    mj-0015 Not authorised. The user did not provide valid authorization credentials. 401
    mj-0021 You do not have access to this resource. The AKID does not have access to the resource. 403

    For GET /sms/count:

    Error Code Error Message Case Description Error Related To Status Code
    mj-0004 Type mismatch. Expected type "[t]". The provided value type is unexpected. FromTS, ToTS or StatusCode 400
    mj-0005 Value "[value]" is invalid. Allowed values are: [allowedValues]. The provided value is not in the array of allowed values. StatusCode 400
    mj-0009 The datetime value "[date]" is not a valid RFC3339 datetime format. The timestamp value is not a valid RFC3339 format. FromTS or ToTS 400
    mj-0015 Not authorised. The user did not provide valid authorization credentials. 401
    mj-0021 You do not have access to this resource. The AKID does not have access to the resource. 403
    mj-0025 Value limit exceeded. Max allowed - [number]. The array property contains more than the maximum allowed number of elements. Limit 400

    SMS Stats Export Error Codes

    For POST /sms/export

    Error Code Error Message Case Description Error Related To Status Code
    mj-0002 Malformed JSON, please review the syntax and properties types. The API user sends a Json with an invalid syntax. 400
    mj-0003 Missing mandatory property. A mandatory property is missing or with null value. FromTS or ToTS 400
    mj-0004 Type mismatch. Expected type "[t]". The provided value type is unexpected. FromTS or ToTS 400
    mj-0009 The datetime value "[date]" is not a valid RFC3339 datetime format. The timestamp value is not a valid RFC3339 format. FromTS or ToTS 400
    mj-0015 Not authorised. The user did not provide valid authorization credentials. 401
    mj-0021 You do not have access to this resource. The AKID does not have access to the resource. 403

    For GET /sms/export/{ID}

    Error Code Error Message Case Description Error Related To Status Code
    mj-0003 Missing mandatory property. A mandatory property is missing or with null value. ID 400
    mj-0004 Type mismatch. Expected type "[t]". The provided value type is unexpected. ID 400
    mj-0015 Not authorised. The user did not provide valid authorization credentials. 401
    mj-0021 You do not have access to this resource. The akid does not have access to the resource. 403