« Back to Documentation Overview

send_newsletter

Section: Messages
Version: 1.5.0


Queue a newsletter to be sent.
Conditions:

  • campaign (mandatory) – CAMPAIGN_ID obtained from get_campaigns. Newsletter will be saved in this campaign. Note that it is not the same as selecting contacts – check contacts / get_contacts params for that.
  • from_field (optional) – FROM_FIELD_ID obtained from get_account_from_fields. It represents From header (name and email) in message and will be taken from campaign if not given.
  • reply_to_field (optional) – FROM_FIELD_ID obtained from get_account_from_fields. It represents Reply-To header (email) in message and will not be present if not given.
  • subject (mandatory) – Subject value. All merge-words should be written as GetResponse Dynamic Content syntax. Maximum length is 512 characters.
  • name (optional) – Name value that describes message. Contacts won't see it.
  • editor_engine (optional) - if set to "wysiwyg" will set newsletter to be edit in the new editor. If You want to edit message in advanced editor remove this parameter entirely
  • contents (mandatory) – Allowed keys are plain and html, at least one is mandatory. All merge-words should be written as GetResponse Dynamic Content syntax. Maximum length is 524288 characters each.
  • attachments (optional) - Files that will be attached to message. Field data must be encoded using Base64 algorithm. Filed name represents name of file. Field mime represents media type of file.
  • flags (optional) – Enables extra functionality for a message, see message_flags for available values.
  • contacts / get_contacts or segments / get_segments - Recipients that should receive a newsletter obtained from get_contacts or get_segments. Only one type of selection can be used at a time. Check IDs in conditions for detailed explanation
  • suppressions / get_suppressions (optional) – Suppressions to use with that message. Any contact email address that matches any of the masks in those suppressions will be skipped when sending. Check IDs in conditions for detailed explanation.

Response explanation:
  • contacts - Represents the number of unique email addresses that are set to receive this newsletter chosen by contacts or get_contacts conditions. Presence of contact on suppressions / blacklists does not affect this counter.
  • segments - Represents the number of unique segments that are set to receive this newsletter chosen by segments or get_segments conditions. Segments are evaluated when message is sent, therefore amount of contacts is unknown during API call.

Those counters are mutually exclusive - only one is present depending on how recipients were chosen.
JSON error messages (if any): Missing campaign, Missing From field, Missing Reply-To field, Missing contents, Missing recipients, Cannot mix contact and segment recipients, Dynamic Content syntax error, Daily limit of newsletters exceeded.
Hint: You don’t have to worry about duplicates when sending to multiple campaigns. If the same email exists in my_campaign_1 and my_campaign_2 campaigns then newsletter will be sent only once to this address (chosen randomly).
Important:
You can call that method only 256 times per day.
We only count those clicks which links was embeded in message using {{link}} tag.


Parameters
stringAPI_KEY
object
stringcampaignCAMPAIGN_ID
stringfrom_fieldFROM_FIELD_ID
stringreply_to_fieldFROM_FIELD_ID
stringsubjectMy newsletter
stringnameSay hi
objectcontents
stringplainHello there
stringhtml<h1>Hello</h1>there
arrayattachments
object
stringdataWmHFvMOzxYLEhyBnxJnFm2zEhSBqYcW6xYQu==
stringnameorder.txt
stringmimeapplication/txt
object
stringdataQWxhLGtvdA==
stringnamepeople.csv
stringmimeapplication/csv
arrayflags
stringclicktrack
stringopenrate
arraycontacts
stringCONTACT_ID
stringCONTACT_ID
objectget_contacts
objectemail
stringCONTAINS%example.com
arraysegments
stringSEGMENT_ID
stringSEGMENT_ID
objectget_segments
objectname
stringCONTAINSmy_segment_name%
arraysuppressions
stringSUPPRESSION_ID
stringSUPPRESSION_ID
objectget_suppressions
objectname
stringCONTAINSmy_suppression_name%
Return Value
stringMESSAGE_IDabc123
integerqueued1
integercontacts1024
integersegments4

Example Request JSON

[
    "API_KEY",
    {
        "campaign": "CAMPAIGN_ID",
        "from_field": "FROM_FIELD_ID",
        "reply_to_field": "FROM_FIELD_ID",
        "subject": "My newsletter",
        "name": "Say hi",
        "contents": {
            "plain": "Hello there",
            "html": "<h1>Hello<\/h1>there"
        },
        "attachments": [
            {
                "data": "WmHFvMOzxYLEhyBnxJnFm2zEhSBqYcW6xYQu==",
                "name": "order.txt",
                "mime": "application\/txt"
            },
            {
                "data": "QWxhLGtvdA==",
                "name": "people.csv",
                "mime": "application\/csv"
            }
        ],
        "flags": [
            "clicktrack",
            "openrate"
        ],
        "contacts": [
            "CONTACT_ID",
            "CONTACT_ID"
        ],
        "get_contacts": {
            "email": {
                "CONTAINS": "%example.com"
            }
        },
        "segments": [
            "SEGMENT_ID",
            "SEGMENT_ID"
        ],
        "get_segments": {
            "name": {
                "CONTAINS": "my_segment_name%"
            }
        },
        "suppressions": [
            "SUPPRESSION_ID",
            "SUPPRESSION_ID"
        ],
        "get_suppressions": {
            "name": {
                "CONTAINS": "my_suppression_name%"
            }
        }
    }
]

Example Response JSON

{
    "MESSAGE_ID": "abc123",
    "queued": 1,
    "contacts": 1024,
    "segments": 4
}

Example Error Response JSON

{
    "code": -1,
    "message": "Daily limit of newsletters exceeded"
}
Method-specific Errors
Missing campaign
Missing From field
Missing Reply-To field
Missing contents
Missing recipients
Cannot mix contact and segment recipients
Dynamic Content syntax error
Daily limit of newsletters exceeded
API-wide Errors
API key verification failed API key verification failed
API client IP not allowed API client IP not allowed
Invalid params Attribute params must be reference to hash