Using the API

The HTTP API allows you to send messages to us using JSON over HTTP. You can either talk to the API using your current HTTP library or you can use one of the pre-built libraries.

Full API documentation

General API Instructions

• You should send POST requests to the URLs shown below.
• Parameters should be encoded in the body of the request and application/json should be set as the Content-Type header.
• The response will always be provided as JSON. The status of a request can be determined from the status attribute in the payload you receive. It will be success or error. Further details can be found in the data attribute.

An example response body is shown below:

{
  "status":"success",
  "time":0.02,
  "flags":{},
  "data":{"message_id":"xxxx"}
}

To authenticate to the API you'll need to create an API credential for your mail server through the web interface. This is a random string which is unique to your server.

To authenticate a request to the API, you need to pass this key in the X-Server-API-Key HTTP header.

Sending a message

There are two ways to send a message - you can either provide each attribute needed for the e-mail individually or you can craft your own RFC 2822 message and send this instead.

Full details about these two methods can be found in our API documentation:

• Sending a message
• Sending an RFC 2822 message

For both these methods, the API will return the same information as the result. It will contain the message_id of the message that was sent plus a messages hash with the IDs of the messages that were sent by the server to each recipient.

{
  "message_id":"message-id-in-uuid-format@rp.postal.yourdomain.com",
  "messages":{
    "john@example.com":{"id":37171, "token":"a4udnay1"},
    "mary@example.com":{"id":37172, "token":"bsfhjsdfs"}
  }
}

GET Message

To retrieve a message and its contents, use the GET method with the id (received when sending the message) and _expansions parameters (if you need more information than the basics) for the message from Postal. For more details, refer to the Postal API documentation.

{
  "id": 14,
  "_expansions": true
}

Example cURL Request

You can use the following cURL command to make the request:

curl --location 'https://<your.postal.domain.com>/api/v1/messages/message' \
--header 'X-Server-API-Key: $yourAPIKeyFromTheCredentialsPage' \
--header 'Content-Type: application/json' \
--data '{
  "id": 14,
  "_expansions": true
}'