POST: /messages

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.

Parameters

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.

Response

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 ProZ.com 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.

Example

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": "[email protected]",
        "subject": "Test message",
        "body": "This is only a test."
    }' \
    https://api.proz.com/v2/messages

Example response:

{
    "success": 1,
    "meta": {
        "status": "pending",
        "status_message": "Pending review by ProZ.com 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
}