SendGrid

Connect your SendGrid account once, then push the templates you publish in Maiilo straight into it. Maiilo records every push and tells you when SendGrid is running an older version than the one you published.

Pro feature · Setup takes about 3 minutes · You need a SendGrid account

Before you start

• A Maiilo Pro plan. Connecting SendGrid and pushing templates are Pro features. A Pro trial counts. On Free, the SendGrid card shows Upgrade to Pro instead of the key field.

  If your plan lapses, templates already in SendGrid are not affected and your stored key stays as it is. You just cannot push new versions until you are back on Pro.

• A SendGrid account where you can create API keys (an account owner or an admin).

• At least one published template. Maiilo pushes the version you published, never the draft.

Note

Connecting does not send any email. Maiilo only reads your account to check that the key works and to find out which account it belongs to.

Create an API key in SendGrid

1. In SendGrid, go to Settings → API Keys and choose Create API Key.
2. Name it something you will recognise later, such as Maiilo.
3. Choose Full Access, or choose Restricted Access and give Template Engine read and write access. See the permissions reference.
4. Copy the key. SendGrid shows it only once. It starts with SG..

Connect it in Maiilo

1. Go to Integrations in the Maiilo sidebar (app.maiilo.io/integrations).
2. Paste the key into the SendGrid card, exactly as SendGrid gave it: no quotes, no Bearer prefix, no spaces at either end.
3. Press Connect SendGrid.

Maiilo checks the key with SendGrid before storing it: that it is valid and has Template Engine access. If the check fails, nothing is stored and Maiilo tells you why. See Troubleshooting.

Confirm it worked

The card shows a Connected badge and Connected as followed by your SendGrid account email, so you can check you connected the right account. It also shows when the key was last verified.

If the key cannot read your account email, the card shows your SendGrid username instead, or “your SendGrid account”. That is normal for a restricted key and does not affect pushing. Add user.email.read to the key if you want to see the email.

Push a template

Each template’s details page has a Destination card. It shows SendGrid, whether SendGrid is in sync, which version SendGrid is running, and the push button.

1. Publish the template. If it has never been published, the button reads Publish before pushing.
2. Press Push to SendGrid. Maiilo creates a dynamic template in SendGrid named after your template, with one version named after the Maiilo version number, such as Welcome email (v3).
3. Check it in SendGrid under Dynamic Templates.

Maiilo does not send your email

Pushing puts the template in your SendGrid account. Sending it is up to you, from SendGrid or through SendGrid’s API. Maiilo never sends mail and never touches your contacts.

Subject required

SendGrid requires a subject on every template version, and Maiilo pushes the subject of the published version.

• No subject yet: the button reads Add a subject, then publish. Add one with Edit details, publish, then push.
• Subject added after the last publish: the button reads Publish to include your subject. Publish, then push.

In both cases nothing is sent to SendGrid until you publish.

Pushing again updates in place

After the first push, the button reads Update in SendGrid. Pushing again replaces the content of the existing SendGrid template version instead of adding a new one, so SendGrid has exactly one template per Maiilo template.

If the SendGrid template was deleted in SendGrid, Maiilo creates a new one on the next push and tells you so.

Your full history of versions stays in Maiilo. See History and rollback.

Keep SendGrid in sync

Publishing a new version does not push it automatically. Nothing leaves Maiilo unless you ask, so SendGrid can fall behind after you publish.

Maiilo shows when that happens:

• On the template’s Destination card, with a Behind status and a line such as “SendGrid has v2, you publish v3”. The push button is on the same card.
• In the builder toolbar, where the delivery status shows which version SendGrid has.
• On Needs Attention, in a group listing every template that is behind in SendGrid. Every row starts ticked, so the button reads Re-push all N. Untick any you want to hold back.
• In the sidebar count of items that need attention.

Pushing the latest published version clears it. Maiilo compares the version you published with the version you pushed every time a page loads, so the warning disappears as soon as they match. There is nothing to dismiss.

Re-publishing templates after a shared block change creates new versions, so those templates then show as behind in SendGrid until you push them.

Push history

The details page lists every push attempt for the template, newest first: which version was sent, when, how long it took, and, if it failed, why. Failed attempts are listed on purpose, so if SendGrid does not have what you expect, you can see whether the push ever succeeded.

A template whose latest push in the last 7 days failed also appears on Needs Attention.

Keys and security

A SendGrid key can send mail as you, so here is exactly how Maiilo handles it.

• Verified before it is stored. A key that fails the check is never saved.
• Encrypted. Maiilo stores the key encrypted, with an encryption key held outside the database. A copy of the database alone is not enough to read it.
• Never shown again. No screen in Maiilo displays a stored key, not even masked.
• Your account email and username are stored in plain text, for the “Connected as” label.
• Deleted on disconnect. Disconnecting removes the stored key completely.
• One SendGrid account per Maiilo account. Connecting again replaces the stored key, so old keys do not pile up.

What encryption does not cover

Encryption protects the stored copy of your key. It cannot limit what the key can do inside SendGrid; only SendGrid’s permissions can. A restricted, Template-Engine-only key is safer than a Full Access one: if it ever leaked, it could not send mail.

Replace a key

When SendGrid is connected, the card has no key field. To replace the key:

1. Create the new key in SendGrid.
2. In Maiilo, press Disconnect on the SendGrid card and confirm.
3. Paste the new key and press Connect SendGrid.
4. Once the card shows Connected again, delete the old key in SendGrid.

If the new key belongs to the same SendGrid account, nothing else changes: your templates stay linked to their SendGrid templates, and your push history and sync status carry over. This is true even if the new key has narrower permissions.

Delete the old key in SendGrid last. If you delete it first, Maiilo is left holding a key that no longer works, and your next push fails.

Disconnect

Press Disconnect on the SendGrid card and confirm. The dialog tells you how many templates are linked. Maiilo deletes its copy of your key immediately.

Disconnecting is not revoking

Maiilo deleting its copy does not deactivate the key. It still works in SendGrid for anyone who has it. If a key may have leaked, delete it in SendGrid’s API Keys settings as well.

Templates you already pushed stay in SendGrid, and Maiilo remembers which SendGrid template belongs to each one. Reconnect the same account and everything picks up where it left off.

Connect a different SendGrid account and Maiilo forgets those links, because those templates are in the old account. Your next push creates new templates in the new account; the originals stay in the old one.

Permissions reference

Full Access covers everything. For a restricted key, these are the scopes that matter:

Scope		What it is for
templates.read	Required	Find your existing templates, so Maiilo updates the right one instead of creating duplicates.
templates.create	Required	Create a template the first time you push.
templates.update	Required	Update the template when you push again.
user.email.read	Optional	Shows your account email in the “Connected as” label.
user.username.read	Optional	Used for the label when the email cannot be read.

Maiilo does not ask for, and cannot use, permission to send mail, read contacts, view statistics, or change your account settings.

Your variables in SendGrid

Maiilo’s {{firstName}} syntax is the same as SendGrid’s, and Maiilo creates dynamic templates, which is what makes SendGrid fill variables in. Your variables work as you wrote them.

SendGrid uses Handlebars, which treats a few brace patterns as instructions where Maiilo shows them as plain text:

You typed	Maiilo shows	SendGrid does
{{ firstName }} (with spaces)	the literal text	fills in a variable
{{#if user}}…{{/if}}	the literal text	runs a conditional
{{{value}}}	the literal text	inserts unescaped HTML
{{user.name}}	the literal text	looks up a nested field
an unclosed {{	the literal text	rejects the whole template

Maiilo pushes your HTML exactly as published and never rewrites it. If you meant any of these as literal text, they will behave differently in SendGrid. A single stray {{ makes SendGrid reject the push; see When a push fails.