Skip to content
API Documentation

SMS Delivery Report (MT)

POST
/your-webhook-url/mt
curl --request POST \
  --url https://api.contacta.mx/your-webhook-url/mt \
  --header 'Content-Type: application/json' \
  --header 'User-Agent: contacta.mx' \
  --header 'x-contacta-signature: b6589fc6ab0dc82cf12099d1c2d40ab994e8410c' \
  --header 'x-contacta-time: 1750000000' \
  --header 'x-contacta-user: a94a8fe5ccb19ba61c4c0873d391e987982fbbd3' \
  --data '{ "trace_id": "100000000000000000", "segments": 1, "chars": 42, "encoding": "GSM", "message": "Tu código de verificación es 482913", "phone": "5218112345678", "status": 3 }'

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

Section titled “Parameters”

Header Parameters

Section titled “Header Parameters”
User-Agent
required
string
Allowed values: contacta.mx
Example
contacta.mx

Always set to contacta.mx on webhook requests

x-contacta-time
required
integer
Example
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
Example
a94a8fe5ccb19ba61c4c0873d391e987982fbbd3

SHA1 hash of your API key.

Use this to identify which account sent the webhook.

x-contacta-signature
required
string
Example
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 Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json

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
segments
required

Number of SMS segments the message was split into

integer
chars
required

Total character count of the message

integer
encoding
required

Character encoding used for the message

string
Allowed values: GSM UNICODE
message
required

Content of the outgoing message

string
phone
required

Destination phone number (E.164 without +)

string
status
required

Delivery status code:

  • 3 — Sent and confirmed by the carrier
  • 10 — Rejected by the operator
integer
Allowed values: 3 10
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
}

Responses

Section titled “Responses”

200

Section titled “200”

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