SMS Delivery Report (MT)

Caution

For security reasons, please contact your Account Manager to provide you with an API host.

The host https://api.example.com not is a real endpoint.

POST

/your-webhook-url/mt

• Production

Contacta.mx sends a POST request to your configured webhook URL when a delivery status update is received for an outgoing SMS (Mobile Terminated).

This is not an endpoint you call — configure your webhook URL through request to soporte@contacta.mx and implement this endpoint on your server to receive delivery reports.

Status codes

Code	Meaning
3	Sent and confirmed by the carrier
10	Rejected by the operator

Validating requests

Every webhook request includes the following headers to verify it originates from contacta.mx:

Header	Value
User-Agent	contacta.mx
x-contacta-time	Unix timestamp (seconds)
x-contacta-user	sha1(api_key)
x-contacta-signature	sha1(api_key + x-contacta-time)

Reject requests where the signature does not match or where x-contacta-time is older than your acceptable tolerance window (e.g. 60 seconds).

Parameters

Header Parameters

User-Agent

required

string

Allowed values: contacta.mx

contacta.mx

Always set to contacta.mx on webhook requests

x-contacta-time

required

integer

1750000000

Unix timestamp (seconds) of when the request was sent.

Use this together with x-contacta-signature to validate request freshness and prevent replay attacks.

x-contacta-user

required

string

a94a8fe5ccb19ba61c4c0873d391e987982fbbd3

SHA1 hash of your API key.

Use this to identify which account sent the webhook.

x-contacta-signature

required

string

b6589fc6ab0dc82cf12099d1c2d40ab994e8410c

SHA1 hash of your API key concatenated with the timestamp from x-contacta-time.

Use this to verify the request authenticity:

expected = sha1(api_key + x-contacta-time)
valid    = expected == x-contacta-signature

Request Body ^required

Payload delivered to your webhook URL when a delivery status update is received for an outgoing SMS (MT).

The status field indicates the final delivery result:

• 3 — Sent and confirmed by the carrier
• 10 — Rejected by the operator

object

trace_id

required

ID returned when the SMS was originally sent. Use this to correlate the delivery report with your send request.

string

100000000000000000

segments

required

Number of SMS segments the message was split into

integer

1

chars

required

Total character count of the message

integer

42

encoding

required

Character encoding used for the message

string

Allowed values: GSM UNICODE

GSM

message

required

Content of the outgoing message

string

Tu código de verificación es 482913

phone

required

Destination phone number (E.164 without +)

string

5218112345678

status

required

Delivery status code:

• 3 — Sent and confirmed by the carrier
• 10 — Rejected by the operator

integer

Allowed values: 3 10

3

Examples

Delivery confirmed by carrier

{
  "trace_id": "100000000000000000",
  "segments": 1,
  "chars": 42,
  "encoding": "GSM",
  "message": "Tu código de verificación es 482913",
  "phone": "5218112345678",
  "status": 3
}

Rejected by operator

{
  "trace_id": "100000000000000001",
  "segments": 1,
  "chars": 42,
  "encoding": "GSM",
  "message": "Tu código de verificación es 482913",
  "phone": "5218112345678",
  "status": 10
}

Responses

200

Your server must return HTTP 200 to acknowledge receipt. Any other status code will trigger a retry from contacta.mx.

Examples

Useful for guiding users to view code examples in different developer languages.

Bash

developer@developer:~#

curl -X POST "https://api.example.com/your-webhook-url/mt" \
    -H "Accept: application/json" \
  -H "Connection: keep-alive" \
  -H "Content-Type: application/json" \
  -H "User-Agent: value" \
  -H "x-contacta-time: value" \
  -H "x-contacta-user: value" \
  -H "x-contacta-signature: value" \
  -d '{"trace_id":"100000000000000000","segments":1,"chars":42,"encoding":"GSM","message":"Tu código de verificación es 482913","phone":"5218112345678","status":3}'

Node.js

example.js

  const fetch = require('node-fetch');

  fetch("https://api.example.com/your-webhook-url/mt", {
    method: "POST",
    headers: {
  "Accept": "application/json",
  "Connection": "keep-alive",
  "Content-Type": "application/json",
  "User-Agent": "value",
  "x-contacta-time": "value",
  "x-contacta-user": "value",
  "x-contacta-signature": "value"
},
    body: JSON.stringify({
  "trace_id": "100000000000000000",
  "segments": 1,
  "chars": 42,
  "encoding": "GSM",
  "message": "Tu código de verificación es 482913",
  "phone": "5218112345678",
  "status": 3
})
  })
    .then(res => res.json())
    .then(console.log)
    .catch(console.error);

PHP

example.php

  <?php
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://api.example.com/your-webhook-url/mt",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_HTTPHEADER => [
    "Accept: application/json",
    "Connection: keep-alive",
    "Content-Type: application/json",
    "User-Agent: value",
    "x-contacta-time: value",
    "x-contacta-user: value",
    "x-contacta-signature: value"
    ],
    CURLOPT_POSTFIELDS => json_encode({
  "trace_id": "100000000000000000",
  "segments": 1,
  "chars": 42,
  "encoding": "GSM",
  "message": "Tu código de verificación es 482913",
  "phone": "5218112345678",
  "status": 3
})
  ]);

  $response = curl_exec($curl);
  curl_close($curl);
  echo $response;
  ?>

C-Sharp

example.cs

  using System.Net.Http;
  using System.Text;
  using System.Threading.Tasks;

  var client = new HttpClient();
  var request = new HttpRequestMessage(HttpMethod.POST, "https://api.example.com/your-webhook-url/mt") {
    Content = new StringContent("{
  \"trace_id\": \"100000000000000000\",
  \"segments\": 1,
  \"chars\": 42,
  \"encoding\": \"GSM\",
  \"message\": \"Tu código de verificación es 482913\",
  \"phone\": \"5218112345678\",
  \"status\": 3
}", Encoding.UTF8, "application/json")
  };
  request.Headers.Add("Accept", "application/json");
request.Headers.Add("Connection", "keep-alive");
request.Headers.Add("Content-Type", "application/json");
request.Headers.Add("User-Agent", "value");
request.Headers.Add("x-contacta-time", "value");
request.Headers.Add("x-contacta-user", "value");
request.Headers.Add("x-contacta-signature", "value");
  var response = await client.SendAsync(request);
  var responseBody = await response.Content.ReadAsStringAsync();
  Console.WriteLine(responseBody);

Python

example.py

  import requests
  import json

  url = "https://api.example.com/your-webhook-url/mt"
  headers = {
    "Accept": "application/json",
  "Connection": "keep-alive",
  "Content-Type": "application/json",
  "User-Agent": "value",
  "x-contacta-time": "value",
  "x-contacta-user": "value",
  "x-contacta-signature": "value"
  }
  data = {
  "trace_id": "100000000000000000",
  "segments": 1,
  "chars": 42,
  "encoding": "GSM",
  "message": "Tu código de verificación es 482913",
  "phone": "5218112345678",
  "status": 3
}

  response = requests.post(url, headers=headers, json=data)
  print(response.text)

Java

example.java

  import java.io.OutputStream;
  import java.net.HttpURLConnection;
  import java.net.URL;
  import java.nio.charset.StandardCharsets;

  public class ApiExample {
    public static void main(String[] args) throws Exception {
      URL url = new URL("https://api.example.com/your-webhook-url/mt");
      HttpURLConnection conn = (HttpURLConnection) url.openConnection();
      conn.setRequestMethod("POST");
      conn.setDoOutput(true);
      conn.setRequestProperty("Accept", "application/json");
    conn.setRequestProperty("Connection", "keep-alive");
    conn.setRequestProperty("Content-Type", "application/json");
    conn.setRequestProperty("User-Agent", "value");
    conn.setRequestProperty("x-contacta-time", "value");
    conn.setRequestProperty("x-contacta-user", "value");
    conn.setRequestProperty("x-contacta-signature", "value");

      String jsonInputString = "{\"trace_id\":\"100000000000000000\",\"segments\":1,\"chars\":42,\"encoding\":\"GSM\",\"message\":\"Tu código de verificación es 482913\",\"phone\":\"5218112345678\",\"status\":3}";
      try(OutputStream os = conn.getOutputStream()) {
          byte[] input = jsonInputString.getBytes(StandardCharsets.UTF_8);
          os.write(input, 0, input.length);
      }

      int code = conn.getResponseCode();
      System.out.println("Response code: " + code);
    }
  }