How to Use the Tifamail API to Send Branded Email and Generate Documents From Your Software

How to Use the Tifamail API

The Tifamail REST API lets your own software - an ERP, CRM, school management system, booking platform or website - send email, generate AI documents and schedule meetings through your Tifamail workspace. The best part: everything the API sends automatically uses your company's brand templates, so system emails look exactly like the ones your staff send.

What You Can Do With the API

Step 1: Create an API Key

API keys are created by a company Admin inside the Tifamail admin settings. Give each integration its own key (for example "ERP invoices" and "Website contact form") so you can revoke one without breaking the others. Keys are stored hashed on Tifamail's side, so copy the key when it is shown - it cannot be displayed again.

Step 2: Authenticate

The base URL is https://tifamail.com/api/v1. Every request sends the key as a Bearer token, and requests and responses are JSON (UTF-8), with timestamps in ISO 8601 UTC. Successful responses wrap the result in a data object.

GET https://tifamail.com/api/v1/workspace
Authorization: Bearer YOUR_API_KEY
Accept: application/json

Step 3: Send Your First Branded Email

A typical send request includes the sending mailbox, recipients, subject and body. Tifamail wraps the content in your chosen brand template and signs it with DKIM for your domain. Check the API reference for the exact field names of each endpoint before you build.

Step 4: Generate a Document

The document endpoint takes a document type and a plain-language description - the same thing a user would type in the AI studio - and returns a document rendered on your letterhead. This is ideal for sending a branded quotation automatically when a customer requests one on your website. AI calls draw from the company AI wallet, so make sure it has credit and consider per-integration limits.

Step 5: Handle Errors and Limits

Read the "Errors & limits" section of the reference. Build in retries with backoff for temporary errors, never retry on validation errors, and log the response body so problems are easy to diagnose.

Integration Ideas for Kenyan Businesses

• ERP or POS: email branded invoices and receipts when a sale is completed.
• School systems: send fee statements, report-card notices and parents' meeting invitations.
• SACCOs: send member statements and AGM invitations with RSVP tracking.
• Websites: route contact-form submissions into a shared inbox, and auto-reply with a branded acknowledgement.
• Property managers: generate and send rent invoices and tenant notices monthly.

Security Best Practices

• Keep API keys in server-side environment variables - never in front-end JavaScript or a public repository.
• Use one key per integration and revoke unused keys.
• Rotate keys when a developer leaves the project.

For SMS alongside email, see our SMS API integration guide.

Designing a Reliable Integration

A dependable email integration follows a few patterns:

• Queue outbound messages in your own system and send them from a background job, so a temporary network problem does not lose an invoice email.
• Store the message ID returned by the API alongside your own record (order, invoice, member) so you can trace delivery later.
• Make retries safe. Before retrying a send, check whether the earlier attempt actually succeeded, so customers do not receive duplicates.
• Log failures with context: the endpoint, status code and response body.

Example Workflow: Branded Invoices From an ERP

1. A sale is completed in the ERP.
2. The ERP calls the document endpoint with a description of the invoice, or attaches the PDF your ERP already generated.
3. The ERP sends the invoice email to the customer through the API, from accounts@yourcompany.co.ke.
4. The message is wrapped in your brand template and DKIM-signed for your domain.
5. Delivery status appears in Tifamail, and your ERP stores the message ID against the invoice.

Testing Before Going Live

Create a separate API key for testing, send messages to internal addresses first, and check how they render in Gmail, Outlook and on phones. Confirm your domain's DNS records are fully verified before sending to customers, because sending stays blocked until they are.

Controlling AI Spend From Integrations

AI document generation draws from the company AI wallet. For automated workflows, decide which events really need AI generation and which can use a fixed template. Monitor AI usage through the workspace endpoint and in the admin dashboard, and top up the wallet before large campaigns or month-end invoice runs.

Frequently Asked Questions

Is the Tifamail API included in the price? Yes. REST API access is included in the workspace, with AI usage billed from the company AI wallet.

Can I send bulk marketing email through the API? The API is designed for business email such as invoices, notifications and correspondence. For large marketing campaigns, use a dedicated email marketing service and follow consent rules under the Data Protection Act.

Which programming languages can I use? Any language that can make HTTPS requests and handle JSON - PHP, Python, JavaScript, Java, C# and others.

Where is the full reference? The interactive API reference lists every endpoint, field and error code.