global directory of translation services
The translation workplace

POST: /messages

Send a message to one or more account holders.

A single message can be sent to up to 25 recipients.

In some cases, messages may be queued for vetting by staff instead of being delivered immediately. In addition, a recipient's messaging preferences may cause the delivery of some messages to be blocked. Check the message status and status_message in the response for details.

Required authorization scope

When using OAuth2 access tokens, the message.send scope is required to send a message. See scopes in the authentication guide for information about how to request this scope of authorization.


Pass the JSON representation of the message as the POST data.

At least one recipient must be specified in the recipient_uuids attribute. All of the recipients must be valid, or message creation will fail and the message won't be sent to any of the recipients.

Any read-only attributes you set will be ignored.


On success, a 201 Created HTTP status code will be returned, along with a standard JSON response.

In the JSON response, the meta attribute will contain an object that describes the message sending status, including a status attribute with one of the following values:

  • sent: The message was sent.
  • pending: The message has been queued for review by staff before being sent.
  • rejected: The message was rejected.

A status_message attribute will contain a human-readable description of the message status.

A failed_recipients attribute will exist if delivery fails to some recipients but succeeds to others. It will contain a list of the UUIDs of the recipients to whom delivery failed. The status_message will explain the reason for failure.

On error, a standard error response will be returned.


Here's an example of sending a message using curl:

curl -H 'Content-Type: application/json' \
    -H 'X-Proz-API-Key: YOUR_API_KEY' \
    -d '{
        "recipient_uuids": [ "f47ac10b-58cc-4372-a567-0e02b2c3d479", "31c8d3e7-ae48-4a1f-aea7-c72baf19c5fc"],
        "sender_name": "Joe Tester",
        "sender_email": "",
        "subject": "Test message",
        "body": "This is only a test."
    }' \

Example response:

    "success": 1,
    "meta": {
        "status": "pending",
        "status_message": "Pending review by staff. Warning: Delivery to one or more recipients was blocked due to their email preferences. See the list of failed recipients for details.",
        "failed_recipients": [ "31c8d3e7-ae48-4a1f-aea7-c72baf19c5fc" ]
    "data": null