Solutions to common problems with email sending in your Caffeine app.
The AI didn't add email to my app when I asked
Email sending requires a Plus or Pro subscription. If you are on a Basic or Starter plan, the AI will not generate email-sending code. Upgrade your plan and ask again.
If you already have a qualifying plan and the AI still didn't generate email code, try rephrasing your request to be more explicit — for example: "Add email sending to this app. When a user registers, send them a confirmation email."
Emails are not arriving
If an action triggers an email but nothing arrives:
- Check your mail DNS records (external domains only). If your project uses a domain you connected from your own registrar, verify that all mail DNS records shown by Caffeine during domain setup are correctly configured. This includes three CNAME records for DKIM, a TXT record for SPF, and a TXT record for DMARC. If any of these records are missing or incorrect, emails will not be delivered — and there is no error message. You can use a tool like Google Admin Toolbox to check whether your DNS records are published correctly. This is the most common cause of email failures on external domains.
- Check your spam folder. Emails sent through Caffeine's infrastructure may be filtered by some spam systems, especially during testing.
- Confirm the action actually ran. Open your app and verify the triggering action completed without errors.
- Check the recipient address. Typos in email addresses stored in your app will cause silent delivery failures — the system won't surface an error to the user.
- Wait a moment. Delivery is normally near-instant, but occasional delays of up to a minute can occur.
Marketing emails are not being delivered to all my subscribers
Marketing emails are only sent to recipients who meet both of these conditions:
- They have verified their email address (clicked the verification link)
- They are subscribed to the specific topic the email is being sent to
If a subscriber hasn't completed email verification, they are silently excluded. Make sure your app's registration or onboarding flow sends a verification email and prompts users to confirm their address before they are added to marketing lists.
The verification link in my email doesn't work
If you added email verification to your app and the link doesn't work, check the email template. The system replaces the placeholder {{VERIFICATION_URL}} with the actual verification link. If that placeholder is missing or misspelled in the email body, the link won't be generated correctly.
Ask the AI to review or fix the email verification template if the link is broken: "The verification link in the confirmation email isn't working — please check the email template."
The unsubscribe link in my marketing email doesn't work
Marketing emails must include the placeholder {{UNSUBSCRIBE_URL}} in the email body. The system replaces this with a unique per-recipient unsubscribe link. If the placeholder is absent, the system appends a default unsubscribe link automatically — but if the link in the message is broken or leads to an error, ask the AI to fix the email template.
A user says they can't unsubscribe
If a user clicks the unsubscribe link and gets an error, or if they're still receiving emails after unsubscribing, contact support. The unsubscribe mechanism is handled by Caffeine's infrastructure — it's not something you can debug or fix directly in your app's code.
Calendar invitations are not appearing in recipients' calendars
Calendar invitations are sent as standard iCalendar (.ics) attachments. Most email clients (Gmail, Apple Mail, Outlook) display these as calendar events automatically. If a recipient doesn't see the event:
- Ask them to check that their email client supports iCalendar attachments and has the feature enabled.
- The invitation can also be downloaded as a
.icsfile and opened manually in any calendar application.
RSVPs are not currently supported — attendees cannot accept or decline through the invitation itself.
My app says "Not enough cycles to send email"
Sending email uses ICP cycles from your app's canister. If the canister runs low on cycles, email sends fail. This is managed by Caffeine's infrastructure for deployed apps on qualifying plans. If you see this error, contact support — it typically indicates a resource issue that needs attention on the platform side.
Emails are not arriving after I connected my own domain
If your app was sending emails successfully before you connected an external domain, and emails stopped arriving after the switch, the most likely cause is missing mail DNS records. When you connect your own domain, Caffeine displays both web records and mail records. The mail records (DKIM, SPF, and DMARC) are required for email delivery from your domain. If only the web records were added, your app will load correctly at the custom domain but emails will silently fail to send.
Go back to the domain setup instructions in Caffeine and verify that all DNS records — including the mail records — are added at your registrar.
Something else is wrong with email in my app
Email sending is currently in beta. If you encounter an issue that isn't covered here, contact support with a description of what you expected to happen and what happened instead. Include your project name and, if possible, the time and recipient address of the failed send.