Supercharge Your Automations: Integrating Third-Party APIs with action.do

In the world of modern software and business, no application is an island. Your agentic workflows and automations are most powerful when they can communicate with the outside world—to send emails, process payments, update a CRM, or post notifications. This is where third-party APIs come in, and action.do provides the perfect framework to manage these integrations with simplicity and power.

At its core, automation is about connecting systems. action.do provides the building blocks—atomic actions—to create a robust and scalable "business-as-code" architecture. Let's dive into how you can use these actions to seamlessly integrate any third-party API into your workflows.

Why Encapsulate API Calls in Atomic Actions?

You could make a raw fetch call directly within a larger script, but this approach quickly becomes messy, repetitive, and difficult to maintain. By wrapping each third-party API call in an atomic action, you unlock several key advantages:

• Abstraction & Simplicity: Hide the complexity of authentication, specific endpoints, and error handling behind a simple, well-named action. Instead of remembering the intricacies of the Stripe API, your workflow simply calls create-customer-invoice.
• Reusability (DRY): Following the "Don't Repeat Yourself" principle, you can define an action like send-slack-notification once and use it across dozens of different workflows. If Slack changes its API, you only have one place to update.
• Testability: Atomic actions are self-contained units that are incredibly easy to test in isolation. You can verify that your API integration works correctly without having to trigger an entire complex business process.
• Robust Error Handling: The atomic nature of an action means it either succeeds completely or fails entirely, preventing partial, corrupt states. You can build tailored error-handling and retry logic directly within the action's handler, making your overall system more resilient.

Anatomy of an API-Calling Action

Let's break down how to build an action that interacts with an external service. We'll use the common example of sending a welcome email, which would likely involve an API call to a service like SendGrid, Mailgun, or AWS SES.

The structure is simple and declarative:

import { action } from '@do-sdk/core';
// Import the SDK for your email service
import { mailgunClient } from '../lib/mailgun';

export const sendWelcomeEmail = action({
  name: 'send-welcome-email',
  description: 'Sends a welcome email to a new user via Mailgun.',
  // 1. Define the inputs your action needs
  inputs: {
    to: { type: 'string', required: true },
    name: { type: 'string', required: true }
  },
  // 2. Implement the core logic in the handler
  handler: async ({ inputs, context }) => {
    const { to, name } = inputs;
    // You'd get your API key securely from context or environment variables
    // const apiKey = context.secrets.MAILGUN_API_KEY;

    console.log(`Preparing to send welcome email to ${name} at ${to}`);

    try {
      // 3. Make the actual API call
      const response = await mailgunClient.messages.create('your-domain.com', {
        from: 'Welcome Team <welcome@your-domain.com>',
        to: [to],
        subject: `Welcome to the platform, ${name}!`,
        text: `Hi ${name},\n\nWe're so glad to have you here!`,
        html: `<h1>Hi ${name},</h1><p>We're so glad to have you here!</p>`
      });

      // 4. Return a structured, successful output
      return { success: true, messageId: response.id };

    } catch (error) {
      console.error('Failed to send email:', error);
      // 5. Handle errors gracefully
      throw new Error(`Email sending failed: ${error.message}`);
    }
  },
});

Let's review the key steps in the handler:

1. Define Inputs: Clearly specify the data your action needs. This becomes the public interface for your action.
2. Implement Handler: This is where the magic happens. The handler is an async function that receives the inputs and a context object (useful for accessing secrets, logs, and other runtime information).
3. Make the API Call: Use a third-party SDK (like @mailgun.js or stripe) or a standard fetch call to interact with the external service. Best Practice: Always wrap this logic in a try...catch block.
4. Return Success: On a successful API call, return a useful, structured object. This output can be used by subsequent actions in a larger workflow.
5. Handle Errors: If the API call fails, log the error and throw a new, more descriptive error. The action.do runtime will catch this and mark the action as failed, preventing the workflow from continuing in an inconsistent state.

From a Single Action to a Powerful Workflow

The true power emerges when you chain these simple building blocks together. An action.do is a single task. A workflow.do is an orchestration of these tasks to achieve a larger business goal.

Imagine a new user signing up. A workflow could orchestrate a series of API-calling actions:

1. create-user-in-db: An action that calls your internal user database API.
2. send-welcome-email: The action we defined above, which calls the Mailgun API.
3. add-user-to-crm: An action that interacts with the Salesforce or HubSpot API.
4. send-slack-notification: An action that posts a message to your team's #new-users channel via the Slack API.

Each step is a simple, reusable, and robust atomic action. The workflow simply defines the order and logic of their execution. If you need to switch your email provider from Mailgun to SendGrid, you only update the send-welcome-email action. The rest of your business logic remains completely untouched.

Ready to stop writing brittle, monolithic scripts and start building powerful, scalable automations? Encapsulate your API calls with action.do and create the robust building blocks your agentic workflows deserve.