How to call the MyGuestlist API

The MyGuestlist API leverages a HTTPS request architecture. All functions are called using a series of HTTP requests to a specific URI.

You must pass a valid API key to most methods of the MyGuestlist API. You can do this by using the following URI syntax.

https://api.myguestlist.com/v1/API KEY/METHOD

Campaigns

The MyGuestlist API allows you to programatically send SMS and Email messages to contacts stored in MyGuestlist.

The following features are supported.

Create a Campaign /campaign_create

Description: Creates a new Campaign draft in MyGuestlist, which can be sent to multiple recipients using the /campaign_send endpoint.
Endpoint URI: https://api.myguestlist.com/v1/API_KEY/campaign_create
HTTP Method POST
Authentication: A valid MyGuestlist API key is required to call this endpoint.

Parameters

When calling this endpoint, you should pass the following Parameters.

Parameter Type Required Description Example Value
campaign_name string Internal name of the Campaign. Not seen by recipients. 2023MAY VIP Members
type string Type of campaign to be sent. Currenly only email is supported email
subject string E The email subject to be sent. Required when type is set to email. Winter has finally come!
from_name string E The from name of the email message. Required when type is set to email. Winterfel Weekly
from_email string The email address this campaign is sent from. Only applicable when the type is set to email. weekly@winterfel.gov
html string The HTML message body for the email message. Required unless url is provided. Only applicable when the type is set to email.
url string A URL to the HTML page for the body of the email message. Required unless html is provided. Only applicable when the type is set to email.
import_images boolean When set to 1 any images in your HTML will be downloaded and stored on MyGuestlist. Only applicable when the type is set to email. 1
Heads Up

Only Email campaigns can be created with this endpoint at this time.

Example Request

The following examples demonstrate how to call this endpoint.

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api.myguestlist.com/v1/YOURTOKENHERE/campaign_create",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "campaign_name=2022MAY%20VIP%20Members&type=email&subject=Winter%20has%20finally%20come!&from_name=Winterfel%20Weekly&from_email=weekly%40winterfel.gov&html=%3Chtml%3E%3Cbody%3E%3Ch1%3EEmail%20content!%3C%2Fh1%3E%3C%2Fbody%3E%3C%2Fhtml%3E&url=http%3A%2F%2Fwinterfel.gov%2Fmay2022vip.html&import_images=1",
  CURLOPT_HTTPHEADER => array(
    "Content-Type: application/x-www-form-urlencoded",
    "cache-control: no-cache"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
curl --request POST \
  --url https://api.myguestlist.com/v1/YOURTOKENHERE/campaign_create \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --header 'cache-control: no-cache' \
  --data 'campaign_name=2022MAY%20VIP%20Members&type=email&subject=Winter%20has%20finally%20come!&from_name=Winterfel%20Weekly&from_email=weekly%40winterfel.gov&html=%3Chtml%3E%3Cbody%3E%3Ch1%3EEmail%20content!%3C%2Fh1%3E%3C%2Fbody%3E%3C%2Fhtml%3E&url=http%3A%2F%2Fwinterfel.gov%2Fmay2022vip.html&import_images=1'                                         
                                        
var request = require(:"request:");

var options = { method: 'POST',
  url: 'https://api.myguestlist.com/v1/YOURTOKENHERE/campaign_create',
  headers: 
   { 
     'cache-control': 'no-cache',
     'Content-Type': 'application/x-www-form-urlencoded' },
  form: 
   { campaign_name: '2022MAY VIP Members',
     type: 'email',
     subject: 'Winter has finally come!',
     from_name: 'Winterfel Weekly',
     from_email: 'weekly@winterfel.gov',
     html: '<html><body><h1>Email content!</h1></body></html>',
     url: 'http://winterfel.gov/may2022vip.html',
     import_images: '1' } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Example Response

Examples of the responses you may receive when calling this endpoint.

{
    "result": true,
    "message": "Campaign Created",
    "data": {
        "campaign_id": "517f7n2g5g"
    }
}
{
    "result": false,
    "message": "You cannot pass both the URL and HTML field options when sending an email",
    "code": 400
}

Handling Errors

If for any reason your message could not be sent, the result Parameter returned to you will be false. The message may give you a better understanding why your message failed.

Message Reason
Insufficient Credits The MyGuestlist account does not have enough Email credits to send this message. The owner must sign in to MyGuestlist and purchase more credits.
Unable to allocate credits
You cannot pass both the URL and HTML field options when sending an email You should only specify one of HTML or URL to this endpoint.
Missing Option X A required option is missing and must be sent with this request


Send a Campaign /campaign_send

Description: Sends a campaign created from the /campaign_create endpoint to the recipients specified.
Endpoint URI: https://api.myguestlist.com/v1/API_KEY/campaign_send
HTTP Method POST
Authentication: A valid MyGuestlist API key is required to call this endpoint.

Parameters

When calling this endpoint, you should pass the following Parameters.

Parameter Type Required Description Example Value
campaign_id string The campaign ID to be sent 52hh4h2h54v.990289475
category_id string/array A MyGuestlist category ID to send the campaign to. Use /categories for available options. Other options include none, all or uncategorized. See below for explanation. uncategorized
send_at datetime The date and time in ISO-8601 format of when the campaign should be sent. If omitted is sent immediately.

Times are in the timezone of the API key owner.
2024-03-20 15:30:00
age_from number Restrict recipients to this age or older. 21
age_to number Restrict recipients to this age or younger. 28
gender string Restrict recipients to this gender only. Only supports m or f. m
Timezone Warning

If your send_at does not include a timezone, MyGuestlist will use the timezone of the MyGuestlist account which owns the API key.

Example Request

The following examples demonstrate how to call this endpoint.

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api.myguestlist.com/v1/YOURTOKENHERE/campaign_send",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "campaign_id=52hh4h2h54v.990289475&category_id%5B%5D=51c88f63g3&category_id%5B%5D=51c255d784&send_at=2024-03-20%2015%3A30%3A00&age_from=18&age_to=28&gender=f",
  CURLOPT_HTTPHEADER => array(
    "Content-Type: application/x-www-form-urlencoded",
    "cache-control: no-cache"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
curl --request POST \
  --url https://api.myguestlist.com/v1/YOURTOKENHERE/campaign_send \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --header 'cache-control: no-cache' \
  --data 'campaign_id=52hh4h2h54v.990289475&category_id%5B%5D=51c88f63g3&category_id%5B%5D=51c255d784&send_at=2024-03-20%2015%3A30%3A00&age_from=18&age_to=28&gender=f'                                      
                                        
var request = require("request");

var options = { method: 'POST',
  url: 'https://api.myguestlist.com/v1/YOURTOKENHERE/campaign_send',
  headers: 
   { 'cache-control': 'no-cache',
     'Content-Type': 'application/x-www-form-urlencoded' },
  form: 
   { campaign_id: '52hh4h2h54v.990289475',
     'category_id[]': [ '51c88f63g3', '51c255d784' ],
     send_at: '2024-03-20 15:30:00',
     age_from: '18',
     age_to: '28',
     gender: 'f' } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Example Response

Examples of the responses you may receive when calling this endpoint.

{
    "result": true,
    "message": "Campaign Sent",
    "data": {
        "campaign_id": "52hh4h2h54v.990289475",
        "recipients": 12048,
        "send_at": "2024-03-20 15:30:00"
    }
}
{
    "result": false,
    "message": "There were no recipients that matched your search",
    "code": 400
}

Category Modifiers

The category_id field allows you to specify one or more categories for the campaign to be sent to. The following modifiers may be used in place.

Modifier Description
all Sends to all contacts who are assigned to a category. Any contacts who are not assigned to a category will not receive this campaign.
none Sends to all contacts, including uncategorized contacts.
uncategorized Only sends this campaign to contacts who are not assigned any categories.

Handling Errors

If there is an error with your request, the response will contain an error message.

Error Code Reason
400 A bad request, including missing required paramaters. See message description for further help.
6XX See /campaign_verify for error code descriptions in this range.


Cancel a Campaign /campaign_cancel

Description: Cancels and prevents a scheduled campaign from being sent.
Endpoint URI: https://api.myguestlist.com/v1/API_KEY/campaign_cancel
HTTP Method POST
Authentication: A valid MyGuestlist API key is required to call this endpoint.

Parameters

When calling this endpoint, you should pass the following Parameters.

Parameter Type Required Description Example Value
campaign_id string The Campaign ID to be cancelled. 52hh4h2h54v.990289475
Heads Up

Cancelled campaigns are moved to an email draft, and can be viewed in MyGuestlist from the Email tab.

Example Request

The following examples demonstrate how to call this endpoint.

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api.myguestlist.com/v1/YOURTOKENHERE/campaign_cancel",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "campaign_id=52hh4h2h54v.990289475",
  CURLOPT_HTTPHEADER => array(
    "Content-Type: application/x-www-form-urlencoded",
    "cache-control: no-cache"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
curl --request POST \
  --url https://api.myguestlist.com/v1/YOURTOKENHERE/campaign_cancel \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --header 'cache-control: no-cache' \
  --data campaign_id=52hh4h2h54v.990289475                                   
                                        
var request = require("request");

var options = { method: 'POST',
  url: 'https://api.myguestlist.com/v1/YOURTOKENHERE/campaign_cancel',
  headers: 
     'cache-control': 'no-cache',
     'Content-Type': 'application/x-www-form-urlencoded' },
  form: { campaign_id: '52hh4h2h54v.990289475' } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});


Example Response

Examples of the responses you may receive when calling this endpoint.

{
    "result": true,
    "message": "Campaign Cancelled",
    "data": {
        "campaign_id": "52hh4h2h54v.990289475"
    }
}
{
    "result": false,
    "message": "Could not cancel campaign",
    "code": 500
}



Test a Campaign /campaign_test

Description: Allows you to send a test message for a campaign created from the /campaign_create endpoint.
Endpoint URI: https://api.myguestlist.com/v1/API_KEY/campaign_test
HTTP Method POST
Authentication: A valid MyGuestlist API key is required to call this endpoint.

Parameters

When calling this endpoint, you should pass the following Parameters.

Parameter Type Required Description Example Value
campaign_id string ID of the Campaign to send a test message for. 52hh4h2h54v.990289475
to array An array of recipient addresses to be sent to.

If this is an email canpaign, you should specify an array of email addresses to receive the test message.
jon@winterfel.gov
Heads Up

Email addresses provided to this method must be valid email addresses in the correct format.

Example Request

The following examples demonstrate how to call this endpoint.

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api.myguestlist.com/v1/YOURTOKENHERE/campaign_test",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "campaign_id=52hh4h2h54v.990289475&to%5B%5D=jon%40winterfel.gov",
  CURLOPT_HTTPHEADER => array(
    "Content-Type: application/x-www-form-urlencoded",
    "cache-control: no-cache"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
curl --request POST \
  --url https://api.myguestlist.com/v1/YOURTOKENHERE/campaign_test \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --header 'cache-control: no-cache' \
  --data 'campaign_id=52hh4h2h54v.990289475&to%5B%5D=jon%40winterfel.gov'                                        
                                        
var request = require("request");

var options = { method: 'POST',
  url: 'https://api.myguestlist.com/v1/YOURTOKENHERE/campaign_test',
  headers: 
   { 'Postman-Token': '3ee386dd-fb90-4cf5-9b83-587bb5c0ca7c',
     'cache-control': 'no-cache',
     'Content-Type': 'application/x-www-form-urlencoded' },
  form: 
   { campaign_id: '52hh4h2h54v.990289475',
     'to[]': 'jon@winterfel.gov' } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});


Example Response

Examples of the responses you may receive when calling this endpoint.

{
    "result": true,
    "message": "Test Message",
    "data": {
        "campaign_id": "52hh4h2h54v.990289475"
    }
}
{
    "result": false,
    "message": "There was an error getting that campaign",
    "code": 500
}


Verify a Campaign /campaign_verify

Description: Checks that a campaign meets all of the requirements to be sent.
Endpoint URI: https://api.myguestlist.com/v1/API_KEY/campaign_verify
HTTP Method POST
Authentication: A valid MyGuestlist API key is required to call this endpoint.

Parameters

When calling this endpoint, you should pass the following Parameters.

Parameter Type Required Description Example Value
campaign_id string The Campaign ID to be verified. 52hh4h2h54v.990289475
Confusion Alert

Verifying a campaign doesn't actually send anything. If you want to send a test message to yourself, use /campaign_test instead.

Example Request

The following examples demonstrate how to call this endpoint.

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api.myguestlist.com/v1/YOURTOKENHERE/campaign_verify",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "campaign_id=52hh4h2h54v.990289475",
  CURLOPT_HTTPHEADER => array(
    "Content-Type: application/x-www-form-urlencoded",
    "cache-control: no-cache"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
curl --request POST \
  --url https://api.myguestlist.com/v1/YOURTOKENHERE/campaign_verify \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --header 'cache-control: no-cache' \
  --data campaign_id=52hh4h2h54v.990289475                                   
                                        
var request = require("request");

var options = { method: 'POST',
  url: 'https://api.myguestlist.com/v1/YOURTOKENHERE/campaign_verify',
  headers: 
     'cache-control': 'no-cache',
     'Content-Type': 'application/x-www-form-urlencoded' },
  form: { campaign_id: '52hh4h2h54v.990289475' } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});


Example Response

Examples of the responses you may receive when calling this endpoint.

{
    "result": true,
    "message": "Campaign OK",
    "data": {
        "campaign_id": "52hh4h2h54v.990289475"
    }
}
{
    "result": false,
    "message": "The campaign you're trying to send has already been sent - please create a new campaign",
    "code": 609
}

Handling Errors

This endpoint will return error codes and messages which should help your users determine what is wrong with their message and why it can't be sent.

Code Reason
602 Message contents are not satisfactory, message is blank, or you left some default text like 'add some text here..' in your message.
603 Error with the campaign from name or from e-mail address. Ensure your from name is at least 5 characters long, and the e-mail address is valid
605 You are not authorised to send this type of campaign. Please contact MyGuestlist to have this enabled on your account.
401
609 The campaign you're trying to send has already been sent - please create a new campaign
611 You have not entered a subject for your campaign
612 The campaign you're trying to send has been locked because of a previous send request. Please contact support@myguestlist.com for help.
616 Your message body contains invalid links to Forward to a Friend, Unsubscribe, or View Online.

If you've copied and pasted your message, go back and ensure you have used the #Unsubscribe# etc mailmerge tags, available from the Personal Links menu (inside the editor).
617 Your message contains invalid links to a Facebook or Twitter profile. Make sure your links inside your e-mail to 'Follow us on Twitter' or 'Like us on Facebook' are linked to your respective profiles. This isn't done automatically, and we'd hate you to send out this message without linking them first.
618 It looks like you've copied and pasted images directly into your e-mail, or your message contains inline images. You must ensure all images are uploaded using the Filemanager.
619 There appears to be a problem with one of your images.
620 Your message appears to be invalid HTML which may not work well in some e-mail clients. Get your designer or someone with HTML knowledge to make sure the HTML is OK, using the editor in 'advanced mode'.

If you imported this e-mail from a URL or ZIP file, be sure to remove any <meta> tags, and your message is between the <body> tags.
621 Your e-mail message appears to contain Javascript. Javascript is not supported in e-mail clients, and may cause your Campaign to be blocked for security reasons. Please use the editor in 'advanced mode' to remove any <script> tags.
622 There appears to be a problem with your message. No unsubscribe link could be found.
625 Your message appears to contain links you've copied-and-pasted from a previously sent campaign. Please go back and check all links in your message to ensure they are going to the correct URL.
626 There seems to be an old unsubscribe link in your message. Please ensure any links to unsubscribe are pointing to #Unsubscribe# and not a URL
627 There seems to be a placeholder image in your message. Please make sure you've replaced all default images with your own before sending.



Send Single Email /email

Description: Sends an email to the specified email address.

This method sends a single email to a single recipient. To send an email campaign to multiple recipients, see /campaign_create
Endpoint URI: https://api.myguestlist.com/v1/API_KEY/email
HTTP Method POST
Authentication: A valid MyGuestlist API key is required to call this endpoint.

Parameters

When calling this endpoint, you should pass the following Parameters.

Parameter Type Required Description Example Value
to_name string Name of the recipient Jon Snow
to_email email Email address of the recipient jon@winterfel.gov
from_name string The name of the sender King's Landing News
from_email email The email address of the sender kingslanding@marketing.lanister.com
html html The message body of the email in HTML format
subject string The email subject line What's on this month at King's Landing
reference_id string A unique ID for the message. Must be less than 42 characters and only contain alpha-numeric characters. kingsenews001
send_at datetime An ISO-8601 datetime string when to send this message. If omitted, sends immediately. 2017-04-01 23:00:00

Mail Merge Tokens

You may place the following mail merge tokens in the html of your message.

Token Description
#unsubscribe# Replaced with a URL to unsubscribe the contact. If your message does not contain this token, it will be automatically added to the footer of your message.

Example Request

The following examples demonstrate how to call this endpoint.

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api.myguestlist.com/v1/YOURTOKENHERE/email",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "to_name=Jon%20Snow&to_email=jon%40winterfel.gov&from_name=King's%20Landing&from_email=kingslanding%40marketing.lanister.com&html=%3Chtml%3E%3Chead%3E%3Ctitle%3EEmail%3C%2Ftitle%3E%3C%2Fhead%3E%3Cbody%3E%3Cp%3EComing%20up%20this%20month...will%20Jon%20Snow%20be%20king%20of%20the%20North%3F%3C%2Fp%3E%3C%2Fbody%3E%3C%2Fhtml%3E&subject=What's%20on%20this%20month%20at%20King's%20Landing&reference_id=kingsenews001&send_at=2017-04-30%2023%3A00%3A00",
  CURLOPT_HTTPHEADER => array(
    "content-type: application/x-www-form-urlencoded"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
curl --request POST \
  --url https://api.myguestlist.com/v1/YOURTOKENHERE/email \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data 'to_name=Jon%20Snow&to_email=jon%40winterfel.gov&from_name=King'\''s%20Landing&from_email=kingslanding%40marketing.lanister.com&html=%3Chtml%3E%3Chead%3E%3Ctitle%3EEmail%3C%2Ftitle%3E%3C%2Fhead%3E%3Cbody%3E%3Cp%3EComing%20up%20this%20month...will%20Jon%20Snow%20be%20king%20of%20the%20North%3F%3C%2Fp%3E%3C%2Fbody%3E%3C%2Fhtml%3E&subject=What'\''s%20on%20this%20month%20at%20King'\''s%20Landing&reference_id=kingsenews001&send_at=2017-04-30%2023%3A00%3A00'                                            
                                        
var request = require("request");

var options = { method: 'POST',
  url: 'https://api.myguestlist.com/v1/YOURTOKENHERE/email',
  headers: { 'content-type': 'application/x-www-form-urlencoded' },
  body: 'to_name=Jon%20Snow&to_email=jon%40winterfel.gov&from_name=King\'s%20Landing&from_email=kingslanding%40marketing.lanister.com&html=%3Chtml%3E%3Chead%3E%3Ctitle%3EEmail%3C%2Ftitle%3E%3C%2Fhead%3E%3Cbody%3E%3Cp%3EComing%20up%20this%20month...will%20Jon%20Snow%20be%20king%20of%20the%20North%3F%3C%2Fp%3E%3C%2Fbody%3E%3C%2Fhtml%3E&subject=What\'s%20on%20this%20month%20at%20King\'s%20Landing&reference_id=kingsenews001&send_at=2017-04-30%2023%3A00%3A00' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Example Response

Examples of the responses you may receive when calling this endpoint.

{
    "result": true,
    "message": "Message Queued For Delivery"
}
{
    "result": false,
    "message": "Unable To Queue Message"
}

Handling Errors

If for any reason your message could not be sent, the result Parameter returned to you will be false. The message may give you a better understanding why your message failed.

Message Reason
Insufficient Credits The MyGuestlist account does not have enough Email credits to send this message. The owner must sign in to MyGuestlist and purchase more credits.
Unable to allocate credits
Error Sending Email - Invalid Reference ID The reference_id you used in this request is invalid
Reference ID contains invalid characters
Unable To Queue Message There was an error queing the message for delivery. Try again later.

Send Single SMS /sms

Description: Sends an SMS to the specified phone number.
Endpoint URI: https://api.myguestlist.com/v1/API_KEY/sms
HTTP Method POST
Authentication: A valid MyGuestlist API key is required to call this endpoint.

Parameters

When calling this endpoint, you should pass the following Parameters.

Parameter Type Required Description Example Value
from string An alphanumeric string for the from name/number of this message. Maximum 11 characters. Whitespace characters (such as a space) are not permitted. 0412312312
to number The phone number of the SMS recipient 0400000000
message string The message contents of the SMS Tonight sees the return of the famous Ned Stark! STOP #unsubscribe#
reference_id string A unique ID for the message. Must be less than 42 characters and only contain alpha-numeric characters. kingsenews002
send_at datetime An ISO-8601 datetime string when to send this message. If omitted, sends immediately. 2017-04-01 23:00:00

Mail Merge Tokens

You may place the following mail merge tokens in the message of your SMS.

Token Description
#reply# Replaced with a phone number to allow for two-way SMS. This must be placed in the from field. See SMS Inbox for more information.

Example Request

The following examples demonstrate how to call this endpoint.

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api.myguestlist.com/v1/YOURTOKENHERE/sms",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "to=0400000000&from=0412312312&message=%20%09Tonight%20sees%20the%20return%20of%20the%20famous%20Ned%20Stark!%20STOP%20%23unsubscribe%23&reference_id=kingsenews002&send_at=2017-04-30%2023%3A00%3A00",
  CURLOPT_HTTPHEADER => array(
    "content-type: application/x-www-form-urlencoded"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
curl --request POST \
  --url https://api.myguestlist.com/v1/YOURTOKENHERE/sms \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data 'to=0400000000&from=0412312312&message=%20%09Tonight%20sees%20the%20return%20of%20the%20famous%20Ned%20Stark!%20STOP%20%23unsubscribe%23&reference_id=kingsenews002&send_at=2017-04-30%2023%3A00%3A00'
var request = require("request");

var options = { method: 'POST',
  url: 'https://api.myguestlist.com/v1/YOURTOKENHERE/sms',
  headers: { 'content-type': 'application/x-www-form-urlencoded' },
  body: 'to=0400000000&from=0412312312&message=%20%09Tonight%20sees%20the%20return%20of%20the%20famous%20Ned%20Stark!%20STOP%20%23unsubscribe%23&reference_id=kingsenews002&send_at=2017-04-30%2023%3A00%3A00' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Example Response

Examples of the responses you may receive when calling this endpoint.

{
    "result": true,
    "message": "Message Queued For Delivery"
}
{
    "result": false,
    "message": "Message contains invalid characters"
}

Handling Errors

If for any reason your message could not be sent, the result Parameter returned to you will be false. The message may give you a better understanding why your message failed.

Message Reason
Insufficient Credits The MyGuestlist account does not have enough Email credits to send this message. The owner must sign in to MyGuestlist and purchase more credits.
Reference ID not found You did not supply a reference_id to this endpoint.
Error Sending SMS - Invalid Reference ID The reference_id you used in this request is invalid
Reference ID contains invalid characters
Unable To Queue Message There was an error queing the message for delivery. Try again later.
Message contains invalid characters The SMS you are trying to send contains invalid characters, such as accented characters used in languages other than English.
Invalid recipient details The recipient phone number you provided is invalid.

Sent Campaigns /sent_items

Description: Retrieve the messages that have been sent out via this account.
Endpoint URI: https://api.myguestlist.com/v1/API_KEY/sent_items
HTTP Method POST
Authentication: A valid MyGuestlist API key is required to call this endpoint.

Parameters

When calling this endpoint, you should pass the following Parameters.

Parameter Type Required Description Example Value
date_start datetime An ISO-8601 datetime string to start searching from. 2017-04-01 23:00:00
date_end datetime An ISO-8601 datetime string to stop searching at. 2017-04-01 23:00:00
prefix string A prefix of a reference_id to search for. kings
reference_id string Only return items sent with this reference_id kingsenews002
type string The type of message sent. Can be either email, social or sms. email

Example Request

The following examples demonstrate how to call this endpoint.

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api.myguestlist.com/v1/YOURTOKENHERE/sent_items",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "date_start=2017-04-30%2023%3A00%3A00&date_end=2017-04-30%2023%3A30%3A00&prefix=kings&reference_id=kingsenews002&type=sms",
  CURLOPT_HTTPHEADER => array(
    "content-type: application/x-www-form-urlencoded"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
curl --request POST \
  --url https://api.myguestlist.com/v1/YOURTOKENHERE/sent_items \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data 'date_start=2017-04-30%2023%3A00%3A00&date_end=2017-04-30%2023%3A30%3A00&prefix=kings&reference_id=kingsenews002&type=sms'
var request = require("request");

var options = { method: 'POST',
  url: 'https://api.myguestlist.com/v1/YOURTOKENHERE/sent_items',
  headers: { 'content-type': 'application/x-www-form-urlencoded' },
  body: 'date_start=2017-04-30%2023%3A00%3A00&date_end=2017-04-30%2023%3A30%3A00&prefix=kings&reference_id=kingsenews002&type=sms' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Example Response

Examples of the responses you may receive when calling this endpoint.

{
    "result": true,
    "message": "Sent items",
    "data": [
        {
            "reference_id": "kingsenews002",
            "type": "sms",
            "timestamp": "2017-04-01 23:00:00",
            "count": 1,
            "message": "Tonight sees the return of the famous Ned Stark! STOP #unsubscribe#",
            "from_name": "0412312312",
            "count_optout": 0
        },
        {
            "reference_id": "kingsenews001",
            "type": "email",
            "timestamp": "2017-04-01 23:00:00",
            "count": 1,
            "message": "message content",
            "from_name": "King's Landing News",
            "subject": "What's on this month at King's Landing",
            "count_open": 1,
            "count_optout": 0,
            "count_auto_optout": 0,
            "count_bounced": 0,
            "count_spam": 0,
            "count_optout": 0
        }

    ]
}
{
    "result": false,
    "message": "MyGuestlist account disabled"
}

Contacts

The MyGuestlist API allows you to get or update contacts stored in MyGuestlist.

The following features are supported.

Getting Contact Fields /get_contact_fields

Description: The get_contact_fields method allows your system to retrieve the client’s field names within MyGuestlist for field to field mapping between the two systems.
Endpoint URI: https://api.myguestlist.com/v1/API_KEY/get_contact_fields
HTTP Method POST
Authentication: A valid MyGuestlist API key is required to call this endpoint.

Parameters

When calling this endpoint, you should pass the following Parameters in JSON format.

Parameter Type Required Description Example Value
client_id string The client ID is a unique ID assigned to identify the database the contact belongs to. abc123
expand boolean If set to true, the return will contain additional field details including the field type, and any applicable options for that field for single or multiple select field types. true

Example Request

The following examples demonstrate how to call this endpoint.

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api.myguestlist.com/v1/YOURTOKENHERE/get_contact_fields?=",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "{\"client_id\": \"abc123\", \"expand\": true}",
  CURLOPT_HTTPHEADER => array(
    "content-type: application/json"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
curl --request POST \
  --url 'https://api.myguestlist.com/v1/YOURTOKENHERE/get_contact_fields?=' \
  --header 'content-type: application/json' \
  --data '{"client_id": "abc123", "expand": true}'
var request = require("request");

var options = { method: 'POST',
  url: 'https://api.myguestlist.com/v1/YOURTOKENHERE/get_contact_fields',
  qs: { '': '' },
  headers: { 'content-type': 'application/json' },
  body: '{"client_id": "abc123", \"expand\": true}' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Example Response

Examples of the responses you may receive when calling this endpoint.

{
    "fields": [
        "PatronEmail", 
        "PatronMobile", 
        "PatronName", 
        "FavouriteColour"
    ]
}
{
    "fields": [
        {
            "name": "PatronEmail", 
            "type": "string"
        },
        {
            "name": "PatronMobile", 
            "type": "string"
        },
        {
            "name": "PatronName", 
            "type": "string"
        },
        {
            "name": "FavouriteColour", 
            "type": "singleSelect",
            "options": [
                "Green",
                "Red",
                "Blue"
            ]
        }
    ]
}
{
    "result": false,
    "message": "No client ID provided"
}

Available Field Types

MyGuestlist has support for multiple field types, which may be exposed by setting the expand parameter in your request. The following field types are available in MyGuestlist.

Type Description
string A single line text field.
text A multi-line text field.
number A field which only accepts numbers.
date A date field which does not include a time component. Format: yyyy-mm-dd
time A time field which does not include a date component. Format: hh:mm:ss (24 hour format)
datetime A date and time field. Format: yyyy-mm-dd hh:mm:ss
singleSelect A field which only allows selection of one option available in a list. This is normally rendered as a radio button or dropdown.
multipleSelect A field which allows selection of one or more option(s) available in a list. This is normally rendered as a series of checkboxes.
bool A field that only accepts a true or false value.
Sex A field that only accepts a m or f value. Used to denote the Gender of the user

Handling Errors

You may encounter the following errors when calling this endpoint. The result Parameter returned to you will be false. The message may give you a better understanding why your request failed.

Message Reason
No client ID provided You must provide a client_id in your request.
Invalid client ID provided The client_id in your request was not valid.

Getting Contacts /pull_db

Description: The pull_db method provides the ability to extract the entire database or any new and updated records from the database within MyGuestlist.
Endpoint URI: https://api.myguestlist.com/v1/API_KEY/pull_db
HTTP Method POST
Authentication: A valid MyGuestlist API key is required to call this endpoint.

Parameters

When calling this endpoint, you should pass the following Parameters in JSON format.

Parameter Type Required Description Example Value
client_id string The client ID is a unique ID assigned to identify the database the contact belongs to. abc123
touched_from datetime Filter the data by retrieving records inserted or updated from the specified date and time. The parameter is optional and can be set without the touched_to field. Format of the date and time is ISO-8601. 2017-04-30 23:00:00
touched_to datetime Filter the data by retrieving records inserted or updated to the specified date and time. The parameter is optional and can be set without the touched_from field. Format of the date and time is ISO-8601. 2017-04-30 23:00:00
member_id string Filter the data by retrieving records based on POSMemberNumber. The parameter is optional. acb123
MemberNumber string Filter the data by retrieving records based on Member Number. The parameter is optional. acb123
PatronEmail string Filter the data by retrieving records based on the contacts email address. The parameter is optional. bob@mgl.com.au
PatronMobile string Filter the data by retrieving records based on the contacts mobile number. The parameter is optional. 0420987765
PatronName string Filter the data by retrieving contacts that match the first name specified. The parameter is optional. Miranda
CardNumber string Filter the data by retrieving contacts that match the Card Number specified. The parameter is optional. acb123
PatronSurname string Filter the data by retrieving records based on last name of patron. The parameter is optional. abc
Heads Up

Excluding the touched_from and touched_to parameters from the request will retrieve the entire client’s MyGuestlist database. The request may timeout if the database is large.

Example Request

The following examples demonstrate how to call this endpoint.

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api.myguestlist.com/v1/YOURTOKENHERE/pull_db?=",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "{\"touched_from\": \"2017-04-30 23:00:00\", \"touched_to\": \"2017-04-30 23:30:00\", \"client_id\": \"abc123\"}",
  CURLOPT_HTTPHEADER => array(
    "content-type: application/json"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
curl --request POST \
  --url 'https://api.myguestlist.com/v1/YOURTOKENHERE/pull_db?=' \
  --header 'content-type: application/json' \
  --data '{
"touched_from": "2017-04-30 23:00:00", 
"touched_to": "2017-04-30 23:30:00", 
"client_id": "abc123"
}
'
var request = require("request");

var options = { method: 'POST',
  url: 'https://api.myguestlist.com/v1/YOURTOKENHERE/pull_db',
  qs: { '': '' },
  headers: { 'content-type': 'application/json' },
  body: '{"touched_from": "2017-04-30 23:00:00", "touched_to": "2017-04-30 23:30:00", "client_id": "abc123"}\n' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Example Response

Examples of the responses you may receive when calling this endpoint.

[
   {
      "client_id":"abc123",
      "contact_id":"6jg8hfg5v6",
      "mgl_categories":"VIP, Members",
      custom contact fields...
   },
   {
      "client_id":"abc123",
      "contact_id":"6jg8hfg5v7",
      "mgl_categories":"Members",
      custom contact fields...
   }
]
{
    "result": false,
    "message": "No client ID provided"
}

Handling Errors

You may encounter the following errors when calling this endpoint. The result Parameter returned to you will be false. The message may give you a better understanding why your request failed.

Message Reason
No client ID provided You must provide a client_id in your request.
Invalid client ID provided The client_id in your request was not valid.

Adding Contacts /push_contact

Description: The push_contact method provides the ability to insert and update the database within MyGuestlist.
Endpoint URI: https://api.myguestlist.com/v1/API_KEY/push_contact
HTTP Method POST
Authentication: A valid MyGuestlist API key is required to call this endpoint.

Parameters

When calling this endpoint, you should pass the following Parameters in JSON format.

This endpoint expects a JSON array of objects containing the following fields.

Parameter Type Required Description Example Value
client_id string The client ID is a unique ID assigned to identify the database the contact belongs to. abc123
contact_id string The contact ID uniquely identifies a contact in the client’s database within MyGuestlist. Only supply this if you know the MyGuestlist contact record you need to update, otherwise MyGuestlist will handle this for you. 6fs63hthg
mgl_categories string A comma separated list of categories to assign the contact to within MyGuestlist. If a category doesn’t exist it will be created. VIP, Members
Contact Information Fields object The remainder of the fields contain contact information. I.e. name, email, mobile, DOB etc. The information captured in the MyGuestlist database is at the client’s discretion. The fields available can be requested using the get_contact_fields method
Heads Up

As this function provides the ability to sync between the MyGuestlist database and your system/application, validation of the custom contact fields will not occur during the load so the data is consistent between the two databases. The data is assumed to be validated within your system/application.

Example Request

The following examples demonstrate how to call this endpoint.

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api.myguestlist.com/v1/YOURTOKENHERE/push_contact?=",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "[{\"client_id\": \"abc123\",\"contact_id\": \"6fs63hthg\",\"mgl_categories\": \"VIP,Members\",\"PatronName\": \"Jon Snow\",\"PatronEmail\": \"jon@winterfel.gov\"}]",
  CURLOPT_HTTPHEADER => array(
    "content-type: application/json"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
curl --request POST \
  --url 'https://api.myguestlist.com/v1/YOURTOKENHERE/push_contact?=' \
  --header 'content-type: application/json' \
  --data '[
    {
        "client_id": "abc123",
        "contact_id": "6fs63hthg",
        "mgl_categories": "VIP,Members",
        "PatronName": "Jon Snow",
        "PatronEmail": "jon@winterfel.gov"
    }
]'
var request = require("request");

var options = { method: 'POST',
  url: 'https://api.myguestlist.com/v1/YOURTOKENHERE/push_contact',
  qs: { '': '' },
  headers: { 'content-type': 'application/json' },
  body: '[{"client_id": "abc123","contact_id": "6fs63hthg","mgl_categories": "VIP,Members","PatronName": "Jon Snow","PatronEmail": "jon@winterfel.gov"}]' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Example Response

Examples of the responses you may receive when calling this endpoint.

{
    "success": [
        {
            "client_id": "abc123", 
            "contact_id": "6fs63hthg"
        }     
    ],
    "failures": []
}
{
    "success": [],
    "failures": [
        {
            "client_id": "", 
            "contact_id": "6fs63hthg"
            "reason": {
                "code": 1007,
                "desc": "No client ID provided"
            }
        }
    ]
}

Handling Errors

You may encounter the following errors when calling this endpoint. The result Parameter returned to you will be false. The message may give you a better understanding why your request failed.

Message Reason
No client ID provided You must provide a client_id against each contact in your request.
Invalid client ID provided The client_id in your request was not valid.
No such contact in MyGuestlist database The contact_id in your request does not exist in MyGuestlist.
No contact information to add/update There isn't enough information to update this contact.
No email or mobile information You must supply at least a PatronEmail or PatronMobile to add a contact to MyGuestlist.
Duplicate check failed The contact you have provided would cause a duplicate contact to be created in MyGuestlist.
New contact add failed There was an error adding this new contact to MyGuestlist.
Update contact failed There was an error updating this contact in MyGuestlist.

Get Categories /categories

Description: The categories method provides the ability to see all available categories and their IDs for the client specified.
Endpoint URI: https://api.myguestlist.com/v1/API_KEY/categories
HTTP Method POST
Authentication: A valid MyGuestlist API key is required to call this endpoint.

Parameters

This endpoint does not accept any paramaters.



Example Request

The following examples demonstrate how to call this endpoint.

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api.myguestlist.com/v1/YOURTOKENHERE/categories",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
curl --request POST \
  --url 'https://api.myguestlist.com/v1/YOURTOKENHERE/categories' \
  
var request = require("request");

var options = { method: 'POST',
  url: 'https://api.myguestlist.com/v1/YOURTOKENHERE/categories',
  qs: { '': '' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Example Response

Examples of the responses you may receive when calling this endpoint.

{
    "result": true,
    "message": "Categories",
    "data": {
        "categories": [
            {
                "name": "Melbourne", 
                "id": "5157f7g27465"
            },
            {
                "name": "Sydney", 
                "id": "51f82683f63"
            }
        ]
    }
}
{
    "result": false,
    "error": "An error occured",
    "code": 400
}

Purchases

The MyGuestlist API allows you to add purchase data against contacts in MyGuestlist.

The following features are supported.

Adding Purchases /add_purchase

Description: The add_purchase method provides the ability to sync basic transaction and purchase data between the MyGuestlist and your applications databases. This gives your application users the ability to market to customers based on the purchases made.
Endpoint URI: https://api.myguestlist.com/v1/API_KEY/add_purchase
HTTP Method POST
Authentication: A valid MyGuestlist API key is required to call this endpoint.

Parameters

When calling this endpoint, you should pass the following Parameters in JSON format.

Parameter Type Required Description Example Value
client_id string The client ID is a unique ID assigned to identify the database the contact belongs to. abc123
contact_id string The contact ID uniquely identifies a contact in the client’s database within MyGuestlist. 6fs63hthg
tx_id string The transaction ID to group the items purchased in one transaction. If one is not present one will be created on the fly within the MyGuestlist database. 1234
item_cat string The category this purchase belongs to.
item_dep string The department this purchase belongs to.
item_store string The store or location this purchase was made at. Melbourne City
item_brand string The brand or trading name this purchase was made at.
item_code string The code representation of the item purchased.
item_desc string The string representation of the item purchased.
item_adj string The adjustment applied to the item purchased.
item_qty number The quantity purchased. If left blank it will be set to 1. 12
price number The total price paid for the item(s). 147.99
purchased_at datetime The date and time the item was purchased at in ISO-8601 format. 2017-04-01 23:00:00

Example Request

The following examples demonstrate how to call this endpoint.

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api.myguestlist.com/v1/YOURTOKENHERE/add_purchase?=",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "[{\"client_id\": \"abc123\", \"contact_id\": \"6fs63hthg\", \"tx_id\": \"5678\", \"item_cat\": \"Beer\", \"item_dep\": \"Imported\", \"item_code\": \"12344\", \"item_desc\": \"Tiger\", \"item_qty\": 3, \"price\": \"27.00\", \"purchased_at\": \"2017-04-30 23:00:00\" }]",
  CURLOPT_HTTPHEADER => array(
    "content-type: application/json"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
curl --request POST \
  --url 'https://api.myguestlist.com/v1/YOURTOKENHERE/add_purchase?=' \
  --header 'content-type: application/json' \
  --data '[{"client_id": "abc123", "contact_id": "6fs63hthg", "tx_id": "5678", "item_cat": "Beer", "item_dep": "Imported", "item_code": "12344", "item_desc": "Tiger", "item_qty": 3, "price": "27.00", "purchased_at": "2017-04-30 23:00:00" }]'
var request = require("request");

var options = { method: 'POST',
  url: 'https://api.myguestlist.com/v1/YOURTOKENHERE/add_purchase',
  qs: { '': '' },
  headers: { 'content-type': 'application/json' },
  body: '[{"client_id": "abc123", "contact_id": "6fs63hthg", "tx_id": "5678", "item_cat": "Beer", "item_dep": "Imported", "item_code": "12344", "item_desc": "Tiger", "item_qty": 3, "price": "27.00", "purchased_at": "2017-04-30 23:00:00" }]' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Example Response

Examples of the responses you may receive when calling this endpoint.

{
    "success": [
        {
            "client_id": "abc123",
            "contact_id": "6fs63hthg",
            "tx_id": "5678", 
            "item_cat": "Beer", 
            "item_dep": "Imported", 
            "item_code": "12344", 
            "item_desc": "Tiger", 
            "item_qty": 3, 
            "price": "27.00", 
            "purchased_at": "2017-04-30 23:00:00"
        }    
    ],
    "failures": []
}
{
    "success": [],
    "failures": [
        {
            "client_id": "abc123",
            "contact_id": "6fs63hthg",
            "tx_id": "5678", 
            "item_cat": "Beer", 
            "item_dep": "Imported", 
            "item_code": "12344", 
            "item_desc": "Tiger", 
            "item_qty": 3, 
            "price": "27.00", 
            "purchased_at": "2017-04-30 23:00:00"
            "reason": {
                "code": 1007,
                "desc": "No client ID provided"
            }
        }
    ]
}

Handling Errors

You may encounter the following errors when calling this endpoint. The result Parameter returned to you will be false. The message may give you a better understanding why your request failed.

Message Reason
No client ID provided You must provide a client_id against each contact in your request.
Invalid client ID provided The client_id in your request was not valid.
No such contact in MyGuestlist database The contact_id in your request does not exist in MyGuestlist.
No purchase information to add You didn't supply any purchase data.
No item description provided The item_desc in your request was invalid.
No item price provided The price in your request was invalid.
No purchase date and time provided The purchased_at in your request was invalid.
Purchase add failed There was an error adding this purchase to MyGuestlist.

Reservations

The MyGuestlist API allows you to add reservations in MyGuestlist.

The following features are supported.

Getting Reservations /pull_reservations

Description: The pull_reservations method allows your system/application to retrieve the MyGuestlist account reservations and associated contact details.
Endpoint URI: https://api.myguestlist.com/v1/API_KEY/pull_reservations
HTTP Method POST
Authentication: A valid MyGuestlist API key is required to call this endpoint.

Parameters

When calling this endpoint, you should pass the following Parameters in JSON format.

Parameter Type Required Description Example Value
client_id string The client ID is a unique ID assigned to identify the database the contact belongs to. abc123
touched_from datetime Filter the data by retrieving records inserted or updated from the specified date and time. The parameter is optional and can be set without the touched_to field. Format of the date and time is ISO-8601. 2017-04-30 23:00:00
touched_to datetime Filter the data by retrieving records inserted or updated to the specified date and time. The parameter is optional and can be set without the touched_from field. Format of the date and time is ISO-8601. 2017-04-30 23:00:00
Heads Up

Excluding the touched_from and touched_to parameters from the request will retrieve the entire client’s MyGuestlist reservations.

Example Request

The following examples demonstrate how to call this endpoint.

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api.myguestlist.com/v1/YOURTOKENHERE/pull_reservations?=",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "{\"touched_from\": \"2017-04-30 23:00:00\", \"touched_to\": \"2017-04-30 23:30:00\", \"client_id\": \"abc123\"}\n",
  CURLOPT_HTTPHEADER => array(
    "content-type: application/json"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
curl --request POST \
  --url 'https://api.myguestlist.com/v1/YOURTOKENHERE/pull_reservations?=' \
  --header 'content-type: application/json' \
  --data '{"touched_from": "2017-04-30 23:00:00", "touched_to": "2017-04-30 23:30:00", "client_id": "abc123"}
'
var request = require("request");

var options = { method: 'POST',
  url: 'https://api.myguestlist.com/v1/YOURTOKENHERE/pull_reservations',
  qs: { '': '' },
  headers: { 'content-type': 'application/json' },
  body: '{"touched_from": "2017-04-30 23:00:00", "touched_to": "2017-04-30 23:30:00", "client_id": "abc123"}\n' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Example Response

Examples of the responses you may receive when calling this endpoint.

[
    {
      "reservation" : 
         {
            "id":"res29gjgu5y",
            "total_attendees":"23",
            "bookingStatus": "Confirmed",
            //custom reservation fields...
         },
      "contact" :
         {
            "client_id":"abc123",
            "contact_id":"5fgfhejgfu4",
            //custom contact fields...
         }
   }
]
{
    "result": false,
    "message": "MyGuestlist account disabled"
}

Handling Errors

You may encounter the following errors when calling this endpoint. The result Parameter returned to you will be false. The message may give you a better understanding why your request failed.

Message Reason
No client ID provided You must provide a client_id against each contact in your request.
Invalid client ID provided The client_id in your request was not valid.
Reservations not setup for this account The MyGuestlist account has not setup Reservations yet.

Adding Reservations /push_reservations

Description: The push_reservations method allows your system/application to push the client’s reservations and associated contact details into their MyGuestlist account.
Endpoint URI: https://api.myguestlist.com/v1/API_KEY/push_reservations
HTTP Method POST
Authentication: A valid MyGuestlist API key is required to call this endpoint.

Parameters

When calling this endpoint, you should pass the following Parameters in JSON format, like the following example.

[
   {
      "reservation" : 
         {
            "id":"[RESERVATION ID]",
            "total_attendees":"[PAX]",
            "attendee_names ":"[NAMES]",
            custom reservation fields...
         },
      "contact" :
         {
            "client_id":"[CLIENT ID]",
            "contact_id":"[MGL ID]",
            custom contact fields...
         }
   }
]
Parameter Type Required Description Example Value
id string The ID for the new Reservation. abc123
total_attendees number The number of people attending the booking. abc123
attendee_names string or array Either a CSV list of attendee names, or an array of names. Jon, Ned, Joffrey
client_id string The client ID is a unique ID assigned to identify the database the contact belongs to. abc123
contact_id string The contact ID uniquely identifies a contact in the client’s database within MyGuestlist. Only supply this if you know the MyGuestlist contact record you need to update, otherwise MyGuestlist will handle this for you. 6fs63hthg
Reservation Information Fields object The remainder of the reservation fields contain reservation information. I.e. reservation name, date, time etc. The information captured in the MyGuestlist database is at the client’s discretion. The fields available can be requested using the get_reservation_fields method
Contact Information Fields object The remainder of the fields contain contact information. I.e. name, email, mobile, DOB etc. The information captured in the MyGuestlist database is at the client’s discretion. The fields available can be requested using the get_contact_fields method

Example Request

The following examples demonstrate how to call this endpoint.

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api.myguestlist.com/v1/YOURTOKENHERE/push_reservations?=",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "[{\"reservation\" : { \"id\":\"abc123\", \"total_attendees\": \"2\", \"attendee_names \": \"Jon, Ned, Joffrey\", \"Date\": \"2017-04-01\", \"Time\": \"19:00:00\"}, \"contact\" :\n{\"client_id\": \"abc123\", \"contact_id\": \"123\", \"PatronName\": \"Jon Snow\", \"PatronEmail\": \"jon@winterfel.gov\"}}]",
  CURLOPT_HTTPHEADER => array(
    "content-type: application/json"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
curl --request POST \
  --url 'https://api.myguestlist.com/v1/YOURTOKENHERE/push_reservations?=' \
  --header 'content-type: application/json' \
  --data '[{"reservation" : { "id":"abc123", "total_attendees": "2", "attendee_names ": "Jon, Ned, Joffrey", "Date": "2017-04-01", "Time": "19:00:00"}, "contact" :
{"client_id": "abc123", "contact_id": "123", "PatronName": "Jon Snow", "PatronEmail": "jon@winterfel.gov"}}]'
var request = require("request");

var options = { method: 'POST',
  url: 'https://api.myguestlist.com/v1/YOURTOKENHERE/push_reservations',
  qs: { '': '' },
  headers: { 'content-type': 'application/json' },
  body: '[{"reservation" : { "id":"abc123", "total_attendees": "2", "attendee_names ": "Jon, Ned, Joffrey", "Date": "2017-04-01", "Time": "19:00:00"}, "contact" :\n{"client_id": "abc123", "contact_id": "123", "PatronName": "Jon Snow", "PatronEmail": "jon@winterfel.gov"}}]' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Example Response

Examples of the responses you may receive when calling this endpoint.

{
    "success": [
        {
            "client_id": "", 
            "contact_id": "6fs63hthg"
            "reservation_id": "abc123",
        }     
    ],
    "failures": []
}
{
    "success": [],
    "failures": [
        {
            "client_id": "", 
            "contact_id": "6fs63hthg"
            "reservation_id": "abc123",
            "reason": {
                "code": 1007,
                "desc": "No client ID provided"
            }
        }
    ]
}

Handling Errors

You may encounter the following errors when calling this endpoint. The result Parameter returned to you will be false. The message may give you a better understanding why your request failed.

Message Reason
No client ID provided You must provide a client_id against each contact in your request.
Invalid client ID provided The client_id in your request was not valid.
Reservations not setup for this account The MyGuestlist account has not setup Reservations yet.

Getting Reservation Fields /get_reservation_fields

Description: The get_reservation_fields method allows the your system/application to retrieve the client’s reservation field names within MyGuestlist for field to field mapping between the two systems.
Endpoint URI: https://api.myguestlist.com/v1/API_KEY/get_reservation_fields
HTTP Method POST
Authentication: A valid MyGuestlist API key is required to call this endpoint.

Parameters

When calling this endpoint, you should pass the following Parameters in JSON format.

Parameter Type Required Description Example Value
client_id string The client ID is a unique ID assigned to identify the database the contact belongs to. abc123

Example Request

The following examples demonstrate how to call this endpoint.

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api.myguestlist.com/v1/YOURTOKENHERE/get_reservation_fields?=",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "{\"client_id\": \"abc123\"}",
  CURLOPT_HTTPHEADER => array(
    "content-type: application/json"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
curl --request POST \
  --url 'https://api.myguestlist.com/v1/YOURTOKENHERE/get_reservation_fields?=' \
  --header 'content-type: application/json' \
  --data '{"client_id": "abc123"}'
var request = require("request");

var options = { method: 'POST',
  url: 'https://api.myguestlist.com/v1/YOURTOKENHERE/get_reservation_fields',
  qs: { '': '' },
  headers: { 'content-type': 'application/json' },
  body: '{"client_id": "abc123"}' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Example Response

Examples of the responses you may receive when calling this endpoint.

{
    "fields": [
        {
            "name": "Date", 
            "type": "date"
        },
        {
            "name": "Time", 
            "type": "time"
        },
        {
            "name": "bookingStatus",
            "type": "singleSelect",
            "options": [
                "Unconfirmed",
                "Pending",
                "Confirmed"
            ]
        },
        {
            "name": "FavouriteColour", 
            "type": "singleSelect",
            "options": [
                "Green",
                "Red",
                "Blue"
            ]
        }
    ]
}
{
    "result": false,
    "message": "No client ID provided"
}

Handling Errors

You may encounter the following errors when calling this endpoint. The result Parameter returned to you will be false. The message may give you a better understanding why your request failed.

Message Reason
No client ID provided You must provide a client_id in your request.
Invalid client ID provided The client_id in your request was not valid.
Reservations not setup for this account The MyGuestlist account has not setup Reservations yet.

SMS Replies

The MyGuestlist API allows you to read replies to SMS messages sent from the MyGuestlist account.

SMS Inbox /sms_inbox

Description: Retrieve SMS replies sent to a virtual number managed by MyGuestlist.
Endpoint URI: https://api.myguestlist.com/v1/API_KEY/sms_inbox
HTTP Method POST
Authentication: A valid MyGuestlist API key is required to call this endpoint.

Parameters

When calling this endpoint, you should pass the following Parameters.

Parameter Type Required Description Example Value
date_start datetime An ISO-8601 datetime string to start searching from. 2017-04-01 23:00:00
date_end datetime An ISO-8601 datetime string to stop searching at. 2017-04-01 23:00:00
prefix string A prefix of a reference_id to search for. kings

Example Request

The following examples demonstrate how to call this endpoint.

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api.myguestlist.com/v1/YOURTOKENHERE/sms_inbox?=",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "date_start=2017-04-30%2023%3A00%3A00&date_end=2017-04-30%2023%3A30%3A00&prefix=kings",
  CURLOPT_HTTPHEADER => array(
    "content-type: application/x-www-form-urlencoded"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
curl --request POST \
  --url 'https://api.myguestlist.com/v1/YOURTOKENHERE/sms_inbox?=' \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data 'date_start=2017-04-30%2023%3A00%3A00&date_end=2017-04-30%2023%3A30%3A00&prefix=kings'
var request = require("request");

var options = { method: 'POST',
  url: 'https://api.myguestlist.com/v1/YOURTOKENHERE/sms_inbox',
  qs: { '': '' },
  headers: { 'content-type': 'application/x-www-form-urlencoded' },
  body: 'date_start=2017-04-30%2023%3A00%3A00&date_end=2017-04-30%2023%3A30%3A00&prefix=kings' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Example Response

Examples of the responses you may receive when calling this endpoint.

{
    "result": true,
    "message": "SMS replies",
    "data": [
        {
            "timestamp": "2017-04-01 23:00:00",
            "number": "sms",
            "to": "0411111111",
            "reference_id": "kingsenews002",
            "message": "Thanks I'll be there",
        }
    ]
}
{
    "result": false,
    "message": "MyGuestlist account disabled"
}

Webhooks

Webhooks are real time notifications pushed from MyGuestlist to a specified URL when the corresponding event occurs on your database within MyGuestlist. Events will only be sent once to the specified URL.

In terms of information data flow between MyGuestlist and your system/application, a Request refers to data sent from MyGuestlist to your system/application and a Response is the data sent back to MyGuestlist.

Setup Required

Webhooks must be enabled on your account by MyGuestlist. There is no ability to configure webhook URL's yourself.

New Contact new_contact

Description: The new_contact event occurs when a new contact is added to the MyGuestlist database.
HTTP Request POST
Webhook Body Format JSON

Webhook Data

When calling your webhook URL, MyGuestlist will pass the following Parameters in JSON format.

Parameter Type Required Description Example Value
client_id string The client ID is a unique ID assigned to identify the database the contact belongs to. abc123
contact_id string The contact ID uniquely identifies a contact in the client’s database within MyGuestlist. 6fs63hthg
Contact Information Fields object The remainder of the fields contain contact information. I.e. name, email, mobile, DOB etc. The information captured in the MyGuestlist database is at the client’s discretion. The fields available can be requested using the get_contact_fields method

Example Webhook

Example of the webhook you may receive.

{
   "client_id":"abc123",
   "contact_id":"65fhf8g74",
   "webhook_type":"new_contact",
   "PatronName": "Jon",
   "PatronEmail": "jsnow@winterfel.gov"
}

Contact Updated contact_update

Description: The contact_update event occurs when information on a contact is updated within the MyGuestlist database.
HTTP Request POST
Webhook Body Format JSON

Webhook Data

When calling your webhook URL, MyGuestlist will pass the following Parameters in JSON format.

Parameter Type Required Description Example Value
client_id string The client ID is a unique ID assigned to identify the database the contact belongs to. abc123
contact_id string The contact ID uniquely identifies a contact in the client’s database within MyGuestlist. 6fs63hthg
Contact Information Fields object The remainder of the fields contain contact information. I.e. name, email, mobile, DOB etc. The information captured in the MyGuestlist database is at the client’s discretion. The fields available can be requested using the get_contact_fields method

Example Webhook

Example of the webhook you may receive.

{
   "client_id":"abc123",
   "contact_id":"65fhf8g74",
   "webhook_type":"contact_update",
   "PatronName": "Jon",
   "PatronEmail": "jsnow@winterfel.gov"
}

Contact Delete delete_contact

Description: The delete_contact event occurs when a contact is deleted within the client’s MyGuestlist database.
HTTP Request POST
Webhook Body Format JSON

Webhook Data

When calling your webhook URL, MyGuestlist will pass the following Parameters in JSON format.

Parameter Type Required Description Example Value
client_id string The client ID is a unique ID assigned to identify the database the contact belongs to. abc123
contact_id string The contact ID uniquely identifies a contact in the client’s database within MyGuestlist. 6fs63hthg

Example Webhook

Example of the webhook you may receive.

{
   "client_id":"abc123",
   "contact_id":"65fhf8g74",
   "webhook_type":"delete_contact"
}