Introduction
Channels
Templates
Contacts
Messages
API
public
beta
Docs Contact Login

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-)
  )
)