Content Type Definitions

The Newsletter Bundle already provides support for two Newsletter APIs (Maileon and Sendgrid).
To match the current logic, we recommend using the following structure when creating a Newsletter Content type in the Ibexa backend.

Content Type: Newsletter

Name	Type	Cannot be empty	Must be defined	Content Field Identifier	Description
Name	ezstring	yes	yes	name	Name of Content
Send Date	ezdate	yes	yes	send_date	The date for sending the Newsletter to subscriber.
Send Time	eztime	no	yes	send_time	The time for sending the Newsletter to subscriber. The combination of this time with "Send Date" is the specific date and time for sending the Newsletter. If this field is left empty, the Newsletter status will be "editing" instead of "sent" when it is sent to the server.
Test E-Mail	ezstring	no	yes	testemail	Send a test Newsletter to a specific Email address.
Newsletter Base Template	ezobjectrelationlist	yes	yes	newsletter_base_template	Associate a Newsletter Basis type of Content.
Newsletter Content	ezlandingpage or any other content field type you may need, such as ezrichtext	yes	yes	newsletter	Specific content of the newsletter.

Special instructions

1) Set Content Type Identifier

When creating the Newsletter Content Type for the project, please set the Content Type Identifier to newsletter as the isNewsletter function in Xrow\NewsletterBundle\EventSubscriber\AbstractContentEventSubscriber checks for this identifier.

2) Configure general fields

As the most basic and important custom Content type Newsletter, the Send Date, Send Time and Test E-Mail three fields must exist, otherwise InvalidConfigurationException and other error messages will be thrown.
Although Send Time and Test E-Mail are not required fields, they can be empty, but they must also be configured in the Newsletter content type. At the same time, the Identifiers of these three fields are also statically written into the logic code (see Xrow\NewsletterBundle\Adapter\NewsletterAdapterInterface), so their "Content Field"-Identifiers must also be set according to send_date, send_time and testemail.

3) Set up fields related to Sendgrid and Maileon

Please use the fixed identifiers name and newsletter_base_template for the Name and Newsletter Base Template fields, as they are directly referenced in the Xrow\NewsletterBundle\Adapter\ServiceAdapter\MaileonAdapter and Xrow\NewsletterBundle\Adapter\ServiceAdapter\SendgridAdapter.

4) Configure field for the Newsletter content

Regarding the Newsletter Content Field, we recommend using the ezlandingpage Field type. This makes it easier to enrich the content on your newsletter-page. Of course, you can also use other Field types such as ezrichtext.
In the getHTML function of the Xrow\NewsletterBundle\Renderer\Renderer class, the newsletter content will be rendered as HTML using an internal sub-request.

Content Type: Newsletter Basis

Name	Type	Cannot be empty	Must be defined	Content Field Identifier	Description
Name	ezstring	yes	yes	name	Name of Content.
Send To	ezobjectrelationlist	yes	yes	subscribers	Here, it is necessary to be associated with another custom content type SubscriberList in order to obtain the "subscribe id" value.
Send From	ezobjectrelationlist	no	no	from	This needs to be associated with another custom Content type SenderList to get sender information (such as the email address that needs to be displayed for the sender, and possibly a corresponding SendID for certain APIs).
Logo	ezimage	no	no	logo	The logo that needs to be displayed in the Newsletter.
Headline	ezstring	no	no	header	The title that needs to be displayed in the Newsletter.
Footer	ezrichtext	no	no	footer	The fixed Footer content that needs to be displayed in the Newsletter.
Color	ezstring	no	no	color	The special color that needs to be displayed in the Newsletter.
Advertisement	ezobjectrelationlist	no	no	ads	Here, you can associate some directories for storing ads, in order to display ads in the Newsletter.

This is a custom content, the given structure is only used as a reference case. Here we just focus on explaining the Send To and Send From fields, which are of the ezobjectrelationlist type of content. Other content fields are not related to the NewsletterBundle logic, please change them according to the different project requirements.

Send To needs to obtain a "subscribe id" (also known as the "List ID") through the SubscriberList Content it is associated with. For the Sendgrid-API, this "subscribe id" is a unique identifier generated by the Sendgrid server for different accounts.
For the Maileon-API, it can be assigned by an editor and used as a unique identifier to distinguish between different Maileon Newsletter accounts.

For example, in a newsletter configuration file, we can use this list_id to map different channels' Maileon-API keys and thereby distinguish which Maileon account the current newsletter should be sent to.

xrow_newsletter:
    maileon:
        channel-01:
            # Mapping between list ID and API key (for Maileon only)
            list_id: 123
            api_key: 'maileon-channel-01-apikey-123'
        channel-02:
            list_id: 456
            api_key: 'maileon-channel-02-apikey-456'

The Send From field needs to obtain the sender's email address and "sendID" through the associated SenderList type of content. Currently, only the Sendgrid API requires the "sendID", whereas the Maileon API does not use it. Therefore, Send From is NOT a required field.

Additionally we inject a base_content parameter in the renderAction method of Xrow\NewsletterBundle\Controller\NewsletterRenderController. This parameter stores the "Newsletter Basis" type of Content associated with the current Newsletter Content.
In the corresponding newsletter-template, we can directly use this parameter to obtain the logo, color, footer and other parameter values that fit this Newsletter.

For example, it can be used like this:

{% if base_content is defined %}
    <div class="footer">
        {{ ibexa_render_field(base_content, 'footer', { 'template': '@ibexadesign/newsletter/fields/ezrichtext_article_line.html.twig' }) }}
    </div>
{% endif %}

Further work

In the future, we may need to optimize this logic to remove the dependency on the List ID. For example, we can use different siteaccesses to distinguish between different channels.

Content Type: SubscriberList and SenderList

SubscriberList

Name	Type	Cannot be empty	Must be defined	Content Field Identifier	Description
Name	ezstring	yes	yes	name	Name of Content.
Subscriber ID	ezinteger	yes	yes	subscribe_id	The SubscribeID (also known as List ID) is automatically generated by the Sendgrid server. The Maileon API uses this ID to distinguish different channels (Siteaccess).
Unsubscribe ID	ezinteger	no	no	unsubscribe_id	The UnsubscribeID generated automatically by the Sendgrid server. The Maileon API does not use this ID.

SenderList

Name	Type	Cannot be empty	Must be defined	Content Field Identifier	Description
Name	ezstring	yes	yes	name	Name of Content.
E-Mail	ezemail	yes	no	email	The email address of the sender.
Sender ID	ezinteger	no	no	sender_id	Generated by the Sendgrid server, the Sender ID is currently only used by the Sendgrid API.

Further work

In future code refactoring, we need to consider whether these two custom contents are necessary and whether the current association structure can be simplified to make the corresponding logic code simpler and more flexible.

---

Last update: February 13, 2023