The Real Magnet REST API allows you to query your account for recipient data, message content, and groups. Continually, the Real Magnet REST API gives users the ability to create and send messages, manage recipient details, and retrieve tracking metrics.
This guide provides a list of calls, their definitions, and their required parameters. The order of the calls in this guide is typically the order in which you may generate calls to the REST API.
- Before attempting to use the REST API, you should understand some of the general rules of Real Magnet recipient data and how that data is used when designing, sending, and analyzing the results of Real Magnet messages. Review the Authentication section below for an overview of some of the important concepts that will influence your understanding of the API.
- You should log in to the Real Magnet system and read Higher Logic's Real Magnet documentation to garner a basic understanding of the Real Magnet platform.
- It's recommended that a new user is created specifically for API calls - the account admin can complete this via the steps here: Manage Users
All REST calls will reference the following base URL:
The Real Magnet REST API is served over HTTPS, and so it is recommended that calls be supplied via HTTPS for security purposes.
To authenticate, use the call:
HTTP requests to the REST API are protected with HTTP Basic authentication. You will use your Real Magnet credentials for the Username and Password.
NOTE: If you don't have the API enabled, create a case.
The REST header will return:
The Real Magnet system supplies for the creation of Assets (Groups, Messages, etc.) and other user-created fields. The character limitation on these fields is indicated below:
|Recipient Level Fields|
|Email, Address 1, Address 2, All Custom Fields||100 Characters|
|Enhanced Personalization Field||250 Characters|
|First name, Last Name, Phone, Fax, City, State, Zip||50 Characters|
|Group Name||50 Characters|
|Message Library Name||250 Characters|
|Message Name||100 Characters|
|Add Recipients||1000 Characters|
|Billing Code||40 Characters|
|Billing Initial||3 Characters|
|Message From||100 Characters|
|Message Subject||100 Characters|
|Preheader Text||100 Characters|
|Reply-To Address||100 Characters|
|Send To for Individual Message||50 Characters|
|Source Codes (1 and 2)||25 Characters|
Additional Information (Header Settings)
Learn more about header settings at Understanding REST Headers and Parameters.
NOTE: The links in the Endpoint column are to internal, call-specific articles. These articles will open in a new window.
(refer to Authentication above)
|POST||Retrieves the LoginID, SessionID, and UserID.|
|AddRecipient/||POST||Adds a new Recipient to Real Magnet based on account Unique Identifier. See Considerations Before Uploading Records with Custom ID as the Unique Identifier to learn more.|
|AddGroup/||POST||Creates a new Group in Real Magnet.|
|CreateDynamicContentBlock/||POST||Creates a Dynamic Content Block.|
|CreateDynamicContentElement/||POST||Creates a Dynamic Content Element.|
|CreateMessage/||POST||Creates a Real Magnet Message.|
|EditDynamicContentElement/||POST||Edits an existing Dynamic Content Element.|
|EditMessage/||POST||Edits an existing Real Magnet Message.|
|EditRecipient/||POST||Edits an existing Real Magnet Recipient.|
|EditRecipientGroups/||POST||Edits an existing Real Magnet Group, to either unsubscribe a recipient from a group or to add them.|
|GetReports/||POST||Retrieves data from custom queries built into the Real Magnet REST service.|
|GetDetailedTracking/||POST||Retrieves tracking information for a message.|
|GetDynamicContentBlocks/||POST||Retrieves existing Dynamic Content Blocks.|
|GetDynamicContentElementDetails/||POST||Retrieves existing Dynamic Content Element details – this would include the recipient details the element is looking for.|
|GetDynamicContentElements/||POST||Retrieves existing Dynamic Content Elements.|
|GetGroupCategories/||POST||Retrieves Group Categories.|
|GetGroupDetails/||POST||Retrieves existing Group details, including total unsubscribed, suppressed and creation details.|
|GetGroupRecipients/||POST||Retrieves a paginated list of recipients from an existing group.|
|GetGroups/||POST||Retrieves a list of existing Groups.|
|GetMessageCategory/||POST||Retrieves a list of existing Message Categories.|
|GetMessageDetails/||POST||Retrieves existing Message details, including creation information.|
|GetMessageLinkTracking/||POST||Retrieves the link tracking for an already deployed Message.|
|GetMessageList/||POST||Retrieves a list of Messages deployed as well as the Groups they were sent to.|
|GetRecipientFields/||POST||Retrieves a list of Recipient fields, including the field name and content.|
|GetRecipientGroups/||POST||Retrieves a list of Groups a Recipient is currently in.|
|GetRecipientHistory/||POST||Retrieves a list of the Recipient’s Real Magnet activity.|
|GetReportMetadata/||POST||Returns the required fields for a request to ExecuteReport/ method.|
|GetReports/||POST||Returns the different reporting options currently available.|
|GetSubscribers/||POST||Retrieves a list of subscribed recipients via an SMP or API calls (SubscribeRecipient/ UnsubscribeRecipient/) within a range of dates.|
|GetSuppressedRecipients/||POST||Retrieves a list of suppressed individuals by Group.|
|GetUnsubscribes/||POST||Retrieves a list of unsubscribed recipients within a range of dates.|
|GetUploadStatus/||POST||Retrieves the upload status of a group, if completed will return the number of accepted records.|
|SearchRecipient/||POST||Searches for a list of recipients using different criteria such as First Name, Email, etc.|
|SendEmailToGroup/||POST||Sends a message with both an HTML and text version to a group of recipients.|
|SendEmailToGroupWithProfile/||POST||Sends a message with both an HTML and text version from a specific Sending Profile to a group of recipients.|
|SendEmailToIndividual/||POST||Send a message to an individual recipient.|
|SubscribeRecipient/||POST||Subscribes a recipient to either a group or a category.|
|UnsubscribeRecipient/||POST||Unsubscribes a recipient to either a group or a category.|
|UploadRecipients/||POST||Uploads recipients to a group.|
|UpsertRecipient/||POST||Adds or edits a recipient with Enhanced Personalized Fields.|