GraphQL Query

Query everything you need in a single GraphQL query.

API Version

Two versions of GraphQL are available in newsletters.

  • Version 1: the legacy version of the API, all examples in this documentation still refer to it
  • Version 2: an extended version of the Sirius GraphQL API

Playground

You can explore and inspect the schema of Sirius Newsletter GraphQL API in its dedicated playground accesible at https://*.sirius.press/api/graphql-newsletters/v1. To be able to get data from your newsletter, don't forget to specify { "x-newsletter-id": <ID-FROM-URL> } in the header section.

You can also activate built-in autocompletion using Ctrl + Space in Sirius GraphQL query editor.

Generate UX by writing a query

Sirius newsletter offers a unique system that generates the UX used by newsletter editors directly from the query defined by developers. It means by writing your query, you also create a tailored admin for editors!

Two special fields allows you to create editable newsletters:

  • textArea: defines an editable text block
  • articlesArea: defines an editable article list block

Example

{
summary: textArea(name: "summary")
@placeholder(value: "A beautiful day")
@label(value: "Daily summary")
@textAreaOptions(multiline: true)
leads: articlesArea(name: "leads", limit: 1)
@label(value: "Lead")
@seed(ids: [3195768])
@areaOptions(warnIfUnpublished: false) {
id
title
image(width: 320, height: 200, aspectRatio: ratio_3x2) {
url
alt
width
height
}
nodes(where: { type: { eq: text }, textNode: { type: { neq: heading } } }) {
__typename
... on TextArticleNode {
textNode {
type
text
}
}
}
}
}

In this example, two custom blocks are defined:

  • A multiline text block:

    • Accessible using summary variable in template
    • With "Daily summary" as label
    • With "A beautiful day" as placeholder
  • A articles list block:

    • Accessible using leads variable in template
    • With title, image and nodes as data accessible on each article
    • With "Lead" as label
    • That should contain at most 1 article
    • That uses article id 3195768 as seed in preview

Directives

All of these directives allow you to customize

Usable on all area fields

  • @label(value: String!): define the label displayed in editor's interface. Usable on textArea and articlesArea


article area label directive (articlesArea)
text area label directive (textArea)

Usable on textArea field

  • @placeholder(value: String!): define the placeholder of the text input.
  • @hint(value: String!): define the hint of the text input.
  • @textAreaOptions(multiline: Boolean): define if the text input accepts multiline or not.

Usable on articlesArea field

  • @areaOptions(warnIfUnpublished: Boolean): enable or disable a warning dialog when an unpublished article is added to the list.



  • @seed(ids: [Int!]!): defines the ids of the articles displayed in preview.

Metadata field

A special metadata field allows you to query metadata defined during the generation of the newsletter.

Example

{
metadata {
environment
date(format: "YYYYMMDDHHmmss")
url
trackingDate: date(format: "YYYYMMDD")
longDate: date(format: "dddd D MMMM YYYY")
provider {
__typename
... on SelligentMetadata {
segment {
api_name
}
}
}
}
}

As an example, data retrieved from this query may help you in building unique campaign names: my_NL_${metadata.date}_${metadata.provider.segment.api_name}_${metadata.environment}. Notice that you can format date field to fit your needs (title, tracking, etc..).

Fetch field

A special fetch field allows you to execute an HTML request directly from GraphQL.

Example

{
fetch(
url: "https://example.com/api/resources/"
method: "get"
headers: [
["content-type", "application/json; charset=UTF-8"]
["x-allow-by-header", "XXX"]
]
) {
status
body
}
}

body is not automatically parsed, if the content is in JSON, you have to use JSON.parse in Handlebars helpers.

Query Forecast

Access Forecast data in newsletters threw forecastTopPageviewArticles field.

Example

{
topViews: forecastTopPageviewArticles(
limit: 4
query: {
since: "2d"
device: "all"
section: "mySection"
publishedSince: "7d"
medium: "all"
}
) {
id
title
url
chapo
pricingTier {
value
}
image(width: 240, height: 120, aspectRatio: ratio_2x1) {
url
alt
width
height
}
}
}
Edit this page on GitHub