GR API Docs

External Content ​

WARNING

External Content and External Lexpad are complementary features but they serve very different purposes. Please read both documentations very carefully and then choose the right solution for your task. Otherwise you may fall into inefficient design antipatterns that will affect sending speed and may generate excessive network traffic.

You should use External Content when you want to include paragraphs that depend on some limited set of variables.

Synopsis ​

Let's assume you have real estate business and you want to present "offer of the day" in your messages.

Of course you want to avoid editing your messages on daily basis and you want to personalize this offer for contacts.

To do so include following tag in your message:

md
{{EXTERNAL `http://example.com/index.html?location={{GEO `city`}}&type={{CUSTOM `interested_in`}}&`}}

When message is sent:

  1. Link is evaluated. For example contact is from "city" Chicago and you stored his preferences in multivalue custom "interested_in", then target link will be http://example.com/index.html?location=Chicago&type=condominiums,duplexes&.
  2. External content is downloaded from this link. Your server should return content correlated with passed params.
  3. Content in placed in message instead of tag.

And each of your contact will automatically get offer of the day matching their location and interests.

General rules ​

  • Your server must respond within 4 seconds.
  • Your server must be capable of handling up to 100 concurrent requests.
  • Response cannot be larger than 64KB per one tag.
  • Returned content must be UTF-8 encoded.
  • Returned content must have valid Dynamic Content syntax.

If any of rules above are broken then message will be sent to contact, but  evaluated URL will be inserted into the message in place of EXTERNAL tag.

Don't! ​

  • Use External Content unique per contact. For example by using {{CONTACT `subscriber_id`}} tag as link parameter or some customs that are unique per contact (like phone number). This will be painfully slow. If you want to do so then you probably need External Lexpad.
  • Format data structures on your side. For example if you want to return "top 20 real estate offers in your location" then you probably need External Lexpad.
  • Return whole www pages from your server (with headers, CSS styles, scripts, and so on). This probably will not work because of broken message structure and limited capabilities of email clients. Your server should only return piece of content that you want in this part of message. As much formatting as possible should remain in static message content.

If we notice high ratio of different URLs compared to amount of sent messages (content is very contact-specific) or inefficient flow we may block this feature until those issues are resolved.

Advanced stuff ​

External Content URL can be parametrized link with campaign predefined values, contact custom field, campaign or contact or message info or contact geo location tags inside URL. Just nest corresponding tags in your external link.

Nested tags have following restrictions:

  • Can not contain default value - {{CONTACT `subscriber_name` `Friend`}} is forbidden.
  • Can not use prettifiers - {{CONTACT `uc(subscriber_name)`}} is forbidden.
  • Are encoded in UTF-8 as URL param, so if {{CONTACT `subscriber_name`}} is "Pabian Paweł" it will be inserted into link as "Pabian%20Pawe%C5%82" to make link valid. Please note that "/" character will also be encoded as "%2F" so do not use nested tag as part of your link path.

Nested tags ​

You can use every Dynamic Content tag in content returned from your server.

For external {{EXTERNAL `http://example.com/about_us` }} your server can return

md
Hi {{CONTACT `ucfw(subscriber_first_name)`}}! We are international company. {{LINK `http://company.com`}}

This response will be re-evaluated (including click tracking), so following content will be inserted into the message.

md
Hi Paweł! We are international company. http://getresponse.com/click.html?x=a62a&..

Multiple externals ​

You can include many external tags in single message.

md
Hi This is what you may need for your pet {{EXTERNAL `http://pet.store.com/?animal={{CUSTOM `pet`}}&limit=1`}} And you may check our other products {{EXTERNAL `http://pet.store.com/general_offer`}}

Reentrance ​

Yes, it is possible to use External Content inside another External Content. Moreover, sometimes it is recommended to achieve better message structure and reduce network traffic. For example:

md
{{EXTERNAL `http://example.com/product?id=123`}}

May return:

md
Hammer drill Neighborex-2000XT  
Buy now and you will get bonus:    
{{EXTERNAL `http://example.com/product?id=456`}}

Where inner external may return: Set of 30 cemented carbide drills. Diameters: 32mm, 30mm, 25mm, ...

This way you won't have to resend the same bonus product content over and over again with each base product purchased.

And if inner product is used frequently it will benefit from content caching (see below).

Caching ​

Fetched content is cached per URL basis. And this cache will be reused every time the same URL is spotted, even if it is in different message.

That allows to reduce network traffic, but may be tricky if you updated returned content under given URL and want it to be fetched again before new message is sent. To force refresh you can add dummy param and ignore it on the server side.:

md
{{EXTERNAL `http://example.com/greeting?message={{CONTACT `message_id`}}`}}

This way URL will be different in every message and cache will not be used.

Content types ​

Be aware of message content type. If you send dual (plain and HTML) messages your external content source should also be able to return plain and HTML. For example use in plain part of the message {{EXTERNAL `http://about.me/main?type=plain"}} and in HTML part of the message use {{EXTERNAL `http://about.me/main?type=html`}} and serve different content from your server depending on type param value.

Authorization ​

If you want to prevent reading external content from other places than GetResponse you can use additional param that will be passed as X-Auth-Token header in HTTP request.

md
{{EXTERNAL `https://example.com/secret_stuff` `400aad99cd7f1191451adb226ba40349`}}

Token will be as safe as message content itself (so for example don't use external with authorization inside external without it) and transmission between GetResponse and your server (use HTTPS).