Messages API reference

Message objects represent the messages sent with Notifuse.

Documented endpoints:

Curl Node PHP

The message object

id string	Message id.
project string	Project id.
channel object	Channel object.
↳ channel.id string	Channel id.
↳ channel.kind string	Channel kind.
↳ channel.key string	Channel key.
↳ channel.data string	Settings sent to the channel while sending the message.
contact object	Contact object.
↳ contact.id string	Contact external id.
↳ contact.timeZone string	Contact time zone used to schedule the message.
notification optional string	Notification id, if it's a transactional message.
template optional object	Template object, if it's a transactional message.
↳ template.id string	Template id.
↳ template.key string	Template key.
↳ template.settings object	Template settings, specific to each channel. Only available for the messages.info endpoint.
campaign optional object	Campaign object, if it's a campaign message.
↳ campaign.id string	Campaign id.
↳ campaign.settings object	Campaign settings. Only available for the messages.info endpoint.
templateData object	JSON data used by the template engine.
compiledTemplates object	JSON object containing the compiled templates, specific to each channel (usually contains subject, text & html). Only available for the messages.info endpoint.
status string	Message lifecycle status.
error optional string	Error description, when status is failed, dropped or bounced.
createdAt string: ISO date	Creation date.
sendAt string: ISO date	Desired sending date.
sentAt optional string: ISO date	Real sending date.
queuedAt optional string: ISO date	Queuing date.
deliveredAt optional string: ISO date	Delivery date. Updated via webhooks if the channel supports it.
droppedAt optional string: ISO date	Dropping date. Updated via webhooks if the channel supports it.
bouncedAt optional string: ISO date	Bouncing date. Updated via webhooks if the channel supports it.
spamAt optional string: ISO date	Complaint date. Updated via webhooks if the channel supports it.
unsubscribedAt optional string: ISO date	Unsubscription date. Updated via webhooks if the channel supports it.
clickedAt optional string: ISO date	Click date. Updated via webhooks if the channel supports it.
openedAt optional string: ISO date	Message opening date. Updated via webhooks if the channel supports it.
clientMetadata optional object	Client metadata specific to each channel (browser, OS, region...). Updated via webhooks for opened and clicked status, if the channel supports it.


{
  "id": "572d93179b90a5351ab1ae3a",
  "project": "acme",
  "channel": {
    "id": "sendgrid-acme",
    "kind": "sendgrid",
    "key": "acme",
    "data": {
      "email": "justin.bieber@yopmail.com"
    }
  },
  "contact": {
    "id": "123",
    "timeZone": "America/New_York"
  },
  "notification": "welcome",
  "template": {
    "id": "welcome_sendgrid-acme_english-v1",
    "key": "english-v1",
    "settings": {
      "from": "me@acme.com",
      "name": "ACME",
      ...
    }
  },
  "templateData": {
    "messageId": "5754ecae6df503f41ce8c162",
    "_verificationToken": "x"
  },
  "compiledTemplates": {
    "subject": "Welcome Justin",
    "text": "Hi Justin, ...",
    ...
  },
  "status": "dropped",
  "error": "Mailbox full."
  "createdAt": "2016-10-22T04:31:13.589Z",
  "sendAt": "2016-10-22T04:31:13.589Z",
  "sentAt": "2016-10-22T04:31:20.589Z",
  "queuedAt": "2016-10-22T04:31:13.589Z",
  "droppedAt": "2016-10-22T04:31:22.589Z"
}

messages.send

Send an array of 50 messages max.

Request

JSON body
notification required string	Notification id.
channel required string	Channel id.
channelOptions optional object	Channel settings to overwrite. Learn more.
template required string	Template key or prefix for split routing.
templateData optional object	Variables for the template engine.
contact required string	Your contact external id (as a string!).
contactProfile optional object	Data to store into your contact's profile Learn more.
contactCreatedAt optional string ISO date	Creation date (ISO 8601) of the contact. Used when the contact is inserted for the first time. Example: 2016-02-04T22:44:30.652Z
sendAt optional string ISO date	Date of the desired sending date. 7 days max in the future!

Response

statusCode integer	HTTP status code returned, 200 even if the request contains malformatted messages.
success boolean	true or false.
queued array of objects	Array of queued and scheduled messages.
failed array of objects	Array of malformatted messages. Each message contains an error key with some explanations.

Example Request


curl -X POST \
  -H 'Authorization: Bearer ${API_KEY}' \
  -H 'Content-Type: application/json' \
  -d '{"messages": [{
      "notification": "welcome",

      "channel": "postmark-myproject",
      "channelOptions": {
        "openTracking": false
      },

      "template": "english-v1",
      "templateData": {
        "_verificationToken": "xxxxxx"
      },

      "contact": "123",
      "contactProfile": {
        "$set": {
          "firstName": "Justin",
          "lastName": "Bieber",
          "email": "justin.bieber@yopmail.com"
        },

        "$push": {
          "tags": "customer"
        },

        "$inc": {
          "totalOrders": 1
        }
      },
      "contactCreatedAt": "2016-02-04T22:44:30.652Z",

      "sendAt": "2016-06-20T05:36:59.285Z"
      }]}' \
  https://api.notifuse.com/v2/messages.send


var Notifuse = require('notifuse'),
    client = new Notifuse.Client(API_KEY);

client.messages.send([
  {
    notification: "welcome",

    channel: "postmark-myproject",
    channelOptions: {
      openTracking: false
    },

    template: "english-v1",
    templateData: {
      _verificationToken: "xxxxxx"
    },

    contact: "123",
    contactProfile: {
      $set: {
        firstName: "Justin",
        lastName: "Bieber",
        email: "justin.bieber@yopmail.com"
      },

      $push: {
        tags: "customer"
      },

      $inc: {
        totalOrders: 1
      }
    },
    contactCreatedAt: "2016-02-04T22:44:30.652Z",

    sendAt: "2016-06-20T05:36:59.285Z"
  }
]).then(function(result){
  // result = API response
})
.cath(function(error){
  // handle error
});


use Notifuse\NotifuseClient;

$client = new NotifuseClient($api_key);

$messages = array(
  array(
    'notification' => 'welcome',

    'channel' => 'postmark-myproject',
    'channelOptions' => array(
      'openTracking' => false
    ),

    'template' => 'english-v1',
    'templateData' => array(
      _verificationToken => 'xxxxxx'
    ),

    'contact' => '123',
    'contactProfile' => array(
      '$set' => array(
        'firstName' => 'Justin',
        'lastName' => 'Bieber',
        'email' => 'justin.bieber@yopmail.com'
      ),

      '$push' => array(
        'tags' => 'customer'
      ),

      '$inc' => array(
        'totalOrders' => 1
      )
    ),
    'contactCreatedAt' => "2016-02-04T22:44:30.652Z",

    'sendAt' => '2016-06-20T05:36:59.285Z'
  )
);

try {
  $response = $client->messages->send($messages);
} catch (Exception $e) {
  // handle error
}

Example Response


{
  "statusCode": 200,
  "success": true,
  "queued": [{-sent message payload-}],
  "failed": []
}


array(
  'statusCode' => 200,
  'success' => true,
  'queued' => array(
    array(-message sent payload-)
  ),
  'failed' => []
)

messages.info

Retrieve a message.

Request

Query parameters
message required string	Message id.

Response

statusCode integer	HTTP status code returned.
message object
↳ message.data object	Contains the message's object.

Example Request


var Notifuse = require('notifuse'),
    client = new Notifuse.Client(API_KEY);

client.messages.info("123").then(function(result){
  // result = API response
})
.catch(function(error){
  // handle error
});


curl -X GET \
  -H 'Authorization: Bearer ${API_KEY}' \
  -H 'Content-Type: application/json' \
  https://api.notifuse.com/v2/messages.info?message=xxx


use Notifuse\NotifuseClient;

$client = new NotifuseClient($api_key);

$messageId = "xxxxxxxxxx";

try {
  $response = $client->messages->info($messageId);
} catch (Exception $e){
  // handle error
}

Example Response


{
  "statusCode": 200,
  "message": {
    "data": {-message object-}
  }
}


array(
  'statusCode' => 200,
  'success' => true,
  'message' => array(
    'data' => array(-message object-)
  )
)