⏰ Estimated setup & testing time: 15min.

​
1. Sign Up and Get API Keys

Create an Account

Sign up at A1Base Dashboard and get your API credentials.
  • Keep these credentials secure as they’ll be used for all API requests

​
2. Create an Email Address

You have two options to create your A1Mail email address:

Dashboard Method

  • Navigate to the Email Dashboard
  • Click “Create New Email Address”
  • Enter your desired email name (e.g., “hello”)
  • Select the domain (@a1send.com)
  • Click “Create”

    • API Method

    Use the API to programmatically create an email address:
    curl --location 'https://api.a1base.com/v1/emails/{account_id}/create-email' \
--header 'X-API-Key: YOUR_API_KEY' \
--header 'X-API-Secret: YOUR_API_SECRET' \
--header 'Content-Type: application/json' \
--data '{
    "address": "hello",
    "domain_name": "a1send.com"
}'
    Note: Email addresses must be between 5 and 30 characters long.

    ​
    3. Test Your New Inbox - Set Up Webhook for Receiving Emails

    ​
    Overview

    To receive incoming emails, you’ll need to configure a webhook that will notify your application when new emails arrive. This section guides you through setting up and testing webhooks in your development environment.

    ​
    3.1. Create a Webhook Endpoint

    First, create an endpoint in your application to receive email notifications. You can use one of our example snippets below or create your own.

    Webhook Implementation Examples

    from flask import Flask, request, jsonify

app = Flask(__name__)

@app.route('/webhook/email', methods=['POST'])
def email_webhook():
    # Get the webhook payload
    data = request.json        
    
    # Process the incoming email
    print(f"Received email: {data['subject']} from {data['sender_address']}")
    
    # Access specific parts of the email
    email_id = data.get('email_id')
    subject = data.get('subject')
    sender = data.get('sender_address')
    recipient = data.get('recipient_address')
    timestamp = data.get('timestamp')
    raw_email = data.get('raw_email_data')
    
    # Your logic here
    # ...
    
    # Return a success response
    return jsonify({"status": "success"}), 200

if __name__ == '__main__':
    app.run(debug=True, port=5000)

    ​
    3.2 Expose Your Local Webhook Endpoint

    To receive emails in your inbox, you need to expose your local webhook endpoint to the internet. You can use ngrok to do this. Run the following command in your CLI to start ngrok: 
    ngrok http 3000
    After starting ngrok
    1. Find the forwarding URL in the ngrok output: 
      Forwarding https://0fcbcda91e79.ngrok.app -> http://localhost:3000
    2. Create the full webhook URL by appending your webhook endpoint path: 
      https://0fcbcda91e79.ngrok.app/webhook/email
    3. Use this complete URL in the A1Mail dashboard webhook settings.

    ​
    3.3 Register Your Webhook in the Dashboard

    Once you have your webhook URL, you need to register it in the A1Mail dashboard:
    1. Log in to your A1Base Dashboard
    2. Navigate to the Email Settings section
    3. Find your email address and click “Configure Webhook”
    4. Enter your full webhook URL (e.g., https://0fcbcda91e79.ngrok.app/webhook/email)
    5. Click “Save Changes”

    ​
    3.4 Test Your Webhook

    Send a test email to your inbox and check if the webhook is receiving the email notifications.

    ​
    4. Send Your First Email

    Now that you’ve confirmed your inbox can receive emails, you can start sending emails as that email address.

    Sending an Email via API

    Use the following API call to send your first email:
    curl --location 'https://api.a1base.com/v1/emails/{account_id}/send' \
--header 'X-API-Key: YOUR_API_KEY' \
--header 'X-API-Secret: YOUR_API_SECRET' \
--header 'Content-Type: application/json' \
--data '{
    "from": "[email protected]",
    "to": "[email protected]",
    "subject": "My First A1Mail Email",
    "text": "Hello from my AI agent! This is my first email sent through A1Mail."
}'

    ​
    5. In Summary

    To ensure everything is working correctly:
    1. Send a test email to your new A1Mail address from your personal email
    2. Check that your webhook receives the incoming email notification
    3. Respond to the email using the A1Mail API
    Now that you’ve set up basic email functionality, explore more advanced features: With these steps completed, your AI agent now has a fully functional email inbox! You can send and receive emails programmatically, enabling your agent to communicate with users through email.
    We’d love to hear from you!Don’t hesitate to reach out to [email protected] or [email protected] if there’s any features you’d like to see or prioritised!